Skip to content

feat: minimal mcp server #316

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
timurbazhirov wants to merge 4 commits into
base: main
Choose a base branch
from
Open

feat: minimal mcp server #316

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
8019739
feat: minimal mcp server
timurbazhirov May 17, 2026
abe0809
feat: code server
timurbazhirov May 17, 2026
b0a89fa
feat: use LLMs
timurbazhirov May 17, 2026
405a0ee
chore: cleanups
timurbazhirov May 17, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions mcp_server/.env.example
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Copy this file to .env and fill in your credentials.
# Obtain them from https://platform.mat3ra.com → Account Preferences → API Tokens

MAT3RA_ACCOUNT_ID=your_account_id_here
MAT3RA_AUTH_TOKEN=your_auth_token_here

# Optional – only needed when working with an organization account
# MAT3RA_ORGANIZATION_ID=your_org_id_here

# API connection settings – defaults are correct for the hosted platform
# MAT3RA_API_HOST=platform.mat3ra.com
# MAT3RA_API_PORT=443
# MAT3RA_API_VERSION=2018-10-01
# MAT3RA_API_SECURE=true
61 changes: 61 additions & 0 deletions mcp_server/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
# Mat3ra MCP Server

Proof-of-concept [Model Context Protocol](https://modelcontextprotocol.io/) server
that exposes the Mat3ra REST API as MCP **tools**, allowing any compatible client
(Claude Desktop, Cursor, etc.) to interact with your Mat3ra account through natural language.

## Available tools

| Tool | Description |
|---|---|
| `list_materials` | Search materials by formula or Mongo query |
| `get_material` | Fetch one material by ID |
| `create_material` | Upload a new material from a JSON config |
| `list_workflows` | List workflows |
| `list_jobs` | List jobs |
| `create_and_submit_job` | Create + submit a job (requires material + workflow IDs) |
| `get_job` | Fetch a job and its current status |

## Setup

```bash
# 1. Create a venv (Python 3.10+)
python3.11 -m venv .venv
source .venv/bin/activate

# 2. Install dependencies
pip install mcp mat3ra-api-client

# 3. Set your credentials
cp mcp_server/.env.example mcp_server/.env
# → edit .env with your ACCOUNT_ID and AUTH_TOKEN
# (get them from https://platform.mat3ra.com → Account Preferences → API Tokens)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated

# 4. Start the server (stdio transport)
export $(cat mcp_server/.env | grep -v '^#' | xargs)
Comment thread
coderabbitai[bot] marked this conversation as resolved.
Outdated
python mcp_server/server.py
```

## Claude Desktop integration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
"mcpServers": {
"mat3ra": {
"command": "/path/to/.venv/bin/python",
"args": ["/path/to/api-examples/mcp_server/server.py"],
"env": {
"MAT3RA_ACCOUNT_ID": "your_account_id",
"MAT3RA_AUTH_TOKEN": "your_auth_token"
}
}
}
}
```

Then restart Claude Desktop. You can now ask things like:
- *"List my Si materials on Mat3ra"*
- *"Create an FCC Si material with lattice parameter 5.43 Å"*
- *"What is the status of job `abc123`?"*
16 changes: 16 additions & 0 deletions mcp_server/pyproject.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
[project]
name = "mat3ra-mcp-server"
version = "0.1.0"
description = "Proof-of-concept MCP server for the Mat3ra API"
requires-python = ">=3.10"
dependencies = [
"mcp>=1.0",
"mat3ra-api-client",
]

[project.scripts]
mat3ra-mcp = "mcp_server.server:main"

Comment on lines +27 to +29

@coderabbitai coderabbitai Bot May 17, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify entrypoint target and callable type in repo sources
rg -n '^\[project\.scripts\]|mat3ra-mcp\s*=|^async def main|^def cli' mcp_server/pyproject.toml mcp_server/server.py

Repository: Exabyte-io/api-examples

Length of output: 224

🏁 Script executed:

#!/bin/bash
# Search for any cli wrapper function and check full context around main
rg -A 5 -B 2 'def cli|def main' mcp_server/server.py

Repository: Exabyte-io/api-examples

Length of output: 336

Console script points to an async function and won't run correctly.

mat3ra-mcp = "mcp_server.server:main" targets async def main() (line 313), so the entry point will call it without awaiting. Expose a sync wrapper (e.g., def cli(): asyncio.run(main())) and point the script to that wrapper.

Suggested change 
# mcp_server/server.py
+def cli() -> None:
+    import asyncio
+    asyncio.run(main())

# mcp_server/pyproject.toml
 [project.scripts]
-mat3ra-mcp = "mcp_server.server:main"
+mat3ra-mcp = "mcp_server.server:cli"
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@mcp_server/pyproject.toml` around lines 11 - 13, The console script currently
points to the async function main(), which will be invoked without awaiting; add
a synchronous wrapper function (e.g., define def cli(): import asyncio and call
asyncio.run(main())) in mcp_server.server and update the project script entry so
mat3ra-mcp points to mcp_server.server:cli instead of mcp_server.server:main;
ensure the new cli wraps the existing async def main() and is exported for the
entry point.

[build-system]
requires = ["setuptools>=64", "wheel"]
build-backend = "setuptools.build_meta"
Loading
Loading