aiida-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
AiiDA MCP
aiida-mcp lets an AI agent work with one AiiDA profile: inspect processes,
discover and submit workflows, and kill, pause or resume running work. Extra
tools from other packages (such as aiida-analyser) plug in through an
entry point.
Use it from Claude Code
The repository is also a Claude Code plugin marketplace. The aiida plugin
bundles this server and a skill that teaches the agent how to check, draft,
confirm, and submit work:
/plugin marketplace add ymzhang0/aiida-mcp
/plugin install aiida@aiida-mcpSee plugin/README.md. Other agents can use the server directly over MCP, as described below.
Related MCP server: agentic-ecos
Run the server
Start one instance for one human-selected runtime:
AIIDA_MCP_PYTHON=/path/to/project/.venv/bin/python \
AIIDA_MCP_PROFILE=silicon \
AIIDA_MCP_WORKSPACE=/path/to/project \
uv run aiida-mcp serve # add --read-only to disable all writesThe Python environment and profile are fixed when the server starts; tools
cannot change either. The server listens on 127.0.0.1:8043 by default
(AIIDA_MCP_HOST, AIIDA_MCP_PORT). Use AIIDA_MCP_TRANSPORT=stdio for
agents that launch MCP servers as subprocesses.
/mcpis the MCP endpoint (streamable HTTP).Set
AIIDA_MCP_TOKENto requireAuthorization: Bearer <token>on both/mcpand/api. Without a token the server only answers requests whoseHostis127.0.0.1/localhost, so a tunnel (ngrok, cloudflared) or a non-loopbackAIIDA_MCP_HOSTneeds the token; the server refuses to start on a non-loopback address without one./apiis the matching read-only HTTP transport used byaiida-project.
Tools
Area | Tools |
Check work |
|
Run work |
|
Structures |
|
Clusters and codes |
|
Control work |
|
Explore data |
|
Plugins | named after the plugin's functions, e.g. |
Tools in bold change the profile. They carry MCP readOnlyHint: false, and
kill also carries destructiveHint: true, so agent clients ask before running
them. --read-only or AIIDA_MCP_READ_ONLY=1 removes them, together with any
plugin tool not marked read-only.
create_computer and create_code only create. They refuse a
label that already exists, so an agent cannot reconfigure a computer that has
running jobs. Before storing anything they test the connection, or check that
the executable exists after the given prepend_text (module loads). Both also
accept the YAML that verdi computer setup --config and
verdi code create --config use.
submit accepts workflows (aiida.workflows) and calculations
(aiida.calculations). Inputs are plain JSON: 2 becomes Int(2),
{"a": 1} becomes Dict, a code is "label@computer", and a stored node is
referenced as {"pk": N} or {"uuid": "..."}. Workflows with
get_builder_from_protocol can instead take protocol, protocol_arguments
and overrides. validate_submission takes the same arguments and only
validates.
Input values are never guessed between "a number" and "the PK of a node":
JSON value | Meaning |
| the stored node |
| a new node holding 42 |
| the value 42 |
| that stored node |
| rejected; use an explicit form |
Tool errors carry the worker's reason and structured detail, not only the JSON-RPC message ("Invalid params").
Architecture
The server never imports AiiDA. A private worker subprocess
(aiida_mcp.worker) runs in the selected Python and talks JSON-RPC over
stdio. It is the only code that touches the ORM. That is why one server can
drive any project environment, including its AiiDA plugins.
Plugins
A package adds tools by declaring an entry point in the project's Python
(the one given by AIIDA_MCP_PYTHON, not the server's environment):
[project.entry-points."aiida_mcp.tools"]
analyser = "aiida_analyser.mcp:tools"The target is a list of plain functions, or a callable that returns one. Each function becomes a tool with the function's name, so name functions verb first:
def diagnose_process(identifier: str, include_outputs: bool = False) -> dict:
"""Diagnose a process: failing branches and why they failed."""
...
diagnose_process.read_only = True # omit for tools that modify the profile
tools = [diagnose_process]The docstring becomes the description the agent reads, so write it for the agent.
Type hints become the JSON input schema; unknown arguments are rejected.
The profile is already loaded when the function runs. It must return JSON-serialisable data, and a non-dict result is wrapped as
{"result": ...}.A name already used by a built-in tool or another plugin is skipped and logged, so choose specific names.
Plugins never import
aiida_mcp. The worker loads them; the server reads their manifest once at start-up. Restart the server after installing a plugin. A plugin that fails to import is logged and skipped. Use--no-pluginsto disable plugin loading entirely.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
MCP-first control plane for ProAgentStore agents and private instances.
Project management shared by people and AI agents, with persistent project state through MCP.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Remote MCP server to run your Atako AI agents: chat, projects, files, integrations and channels.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for the Partiri Cloud PaaS platform. Enables AI agents to manage workspaces, projects, services, deployments, and metrics.231MIT
- AlicenseBqualityBmaintenanceMCP server that initializes, manages, and operates traceable agentic infrastructure across your digital ecosystem, serving as a control plane to know project states, health, and initialize missing setups.371MIT
- AlicenseNot gradedqualityFmaintenanceA durable MCP control plane for starting, observing, steering, continuing, cancelling, and handing off long-running coding agents, with bounded MCP calls and persistent worktrees.14 npmMIT
- FlicenseNot gradedqualityCmaintenanceA local-first MCP control-plane core that gives AI agents persistent project context through workspace registration, reusable skill routing, and health guardians over stdio.4,157 npm-