Introduction¶
Welcome to the aiida-mcp documentation. aiida-mcp is a
Model Context Protocol server for AiiDA. It
lets an MCP client, such as an AI assistant, inspect an AiiDA database and submit calculations through a
small, growing set of calcjob plugins (currently DL_POLY, ChemShell and MLIP).
Warning
The server has write tools that are always on: submit_dlpoly_job, submit_chemshell_job and the
submit_mlip_*_job tools create nodes and start jobs on the daemon. Point the server at an AiiDA
profile you are happy to write to. See Tools for the full list of tools and what each one does.
Quick start¶
aiida-mcp requires Python 3.10 or newer and depends on aiida-core and mcp. It should be
installed in the same Python environment as the AiiDA profile it will serve, typically using
pip:
git clone <this repository>
cd aiida-mcp
python3 -m venv env
source env/bin/activate
pip install -e .
Most calcjob plugins are an optional extra, installed only when you need their tools:
pip install -e ".[mlip]" # MLIP tools (installs aiida-mlip)
pip install -e ".[aiidalab]" # AiiDAlab detection (installs jupyter-server)
pip install -e ".[test]" # pytest, for running the tests
DL_POLY and ChemShell tools are not aiida-mcp extras: install aiida-dlpoly/aiida-chemshell with
their own mcp extra instead, and aiida-mcp discovers them automatically:
pip install "aiida-dlpoly[mcp]"
pip install "aiida-chemshell[mcp]"
A plugin’s tools are only registered if its package is installed; without it, the server runs normally and the plugin’s tools are simply absent. Check the install with:
aiida-mcp --help
Setting up AiiDA¶
The server reads the default AiiDA profile from ~/.aiida (or from the directory given by the
AIIDA_PATH environment variable). If you already have a working profile and daemon, skip ahead to
Running the server.
Create a profile¶
The quickest option is verdi presto. It creates a profile using SQLite that needs no other services,
makes it the default, and configures localhost as a computer:
verdi presto --profile-name presto
If RabbitMQ is running on localhost, verdi presto uses it; otherwise it uses the ZeroMQ broker, which
starts with the daemon. For more control, for example PostgreSQL, see verdi presto --help and
verdi profile setup.
Start the daemon¶
The daemon runs submitted jobs. Without it, jobs wait in the queue and never run:
verdi daemon start
Check the profile¶
verdi profile list # the default profile is marked with *
verdi status # profile, storage, broker and daemon
verdi computer list # should list localhost
To change the default profile, which is the one the server uses:
verdi profile set-default <name>
The server always loads the default profile. If you need it to use another one, change the default
before starting the server, or set AIIDA_PATH to a different configuration directory. See
Managing profiles for how to create and switch profiles at runtime from an MCP client instead.
Setting up calcjob codes¶
Each plugin needs an AiiDA code registered for its executable before submit_* tools for it will work.
DL_POLY¶
Register your DL_POLY executable as a code on the computer it runs on. Use the absolute path to the executable and double-check it exists, because a wrong path only fails when a job runs:
verdi code create core.code.installed \\
--label dl_poly \\
--computer localhost \\
--filepath-executable /path/to/DLPOLY.Z \\
--default-calc-job-plugin dlpoly \\
--no-with-mpi \\
--non-interactive
Drop --no-with-mpi and add --with-mpi to launch through mpirun. If your system needs
environment modules, add --prepend-text "module load mpi" (adjust to your system). A stored code’s
executable path cannot be edited; to fix a wrong path, create a new code or use verdi code duplicate.
ChemShell¶
Register your ChemShell executable as a code on the computer it runs on:
verdi code create core.code.installed \\
--label chemsh \\
--computer localhost \\
--filepath-executable /absolute/path/to/chemsh \\
--default-calc-job-plugin chemshell \\
--no-with-mpi \\
--non-interactive
Whether to pass --with-mpi depends on which executable you point at, not on whether your ChemShell
build is MPI-enabled: use --no-with-mpi for the chemsh wrapper script (it handles launching MPI
itself), and --with-mpi if you point directly at chemsh.x.
MLIP¶
Register the janus executable (from janus-core) as a code. The same code can be used for all four
MLIP job types; --default-calc-job-plugin is just a CLI default suggestion and does not restrict which
entry point the code can be submitted with:
verdi code create core.code.installed \\
--label janus \\
--computer localhost \\
--filepath-executable "$(which janus)" \\
--default-calc-job-plugin mlip.sp \\
--non-interactive
Check any of these with verdi code list and verdi code show <label>.
Running the server¶
The server speaks MCP over stdio by default, which is what most clients use. The client normally starts the server itself:
aiida-mcp # stdio
aiida-mcp --transport streamable-http # HTTP
The HTTP transport listens on http://127.0.0.1:8000/mcp. The host and port are the MCP library’s
defaults and the command line does not change them. The HTTP endpoint has no authentication — anything
that can reach it can call every tool, including the write tools, so leave it bound to localhost.
Connecting a client¶
Configure your MCP client to run the aiida-mcp executable from the virtual environment. Use the
absolute path, since the client usually does not activate the environment:
/path/to/aiida-mcp/env/bin/aiida-mcp
Many clients use a JSON entry like this one. The file location and exact format differ between clients, so check your client’s documentation:
{
"mcpServers": {
"aiida": {
"command": "/path/to/aiida-mcp/env/bin/aiida-mcp"
}
}
}
If the server starts but reports no profile, the client may be running it with a different home
directory or environment; add AIIDA_PATH to the client’s environment settings for the server. The
first tool call takes a few seconds, because AiiDA loads its profile and storage on first use.
If your AiiDA profile lives inside an aiidalab/full-stack Docker container rather than on the local
machine, see Integrating with AiiDAlab for running the server inside that container and connecting to
it over streamable-http instead.
Troubleshooting¶
get_statusshowsprofile_loaded: falseNo default profile was found. Run
verdi profile list. If the client starts the server, check that it sees the same home directory andAIIDA_PATH.- A job stays in the
waitingorcreatedstate The daemon is probably not running. Run
verdi daemon status, thenverdi daemon start.- A newly installed plugin’s tools aren’t showing up
The server only checks for installed plugins on startup, because AiiDA and Python both cache entry point lookups for the lifetime of the process. Call the
rescan_pluginstool, or restart the server, to pick up a plugin package installed afterwards (see Rescanning for plugins). Make sure the package declares anaiida_mcp.pluginsentry point in its own installed metadata.- A job finishes with a non-zero exit status or
excepted Call
get_process_reportwith the PK. Compare the exit status with the matchingdescribe_*_calcjobtool, and check that the code’s executable path exists (verdi code show <code>).- The first call is slow
AiiDA loads the profile and storage on the first call.
- A tool call fails with a generic “Error executing tool” message
Anticipated errors return a clear message; a generic one means something unexpected went wrong. The traceback is in the server’s stderr, so check your client’s MCP logs.