aiida_mcp.server module

MCP server entry point and tool registration.

aiida_mcp.server.get_aiidalab_status() → dict

Report whether an AiiDAlab Jupyter server is running locally, and its URL.

Looks for a running Jupyter server whose working directory looks like an AiiDAlab home directory. The returned URL includes the access token.

Returns:

Whether a server is running and, if so, its URL, pid, root directory and version.

Return type:

dict

aiida_mcp.server.get_node_content(pk: int) → dict

Return the content of a node, for node types where that is supported.

Currently supported: SinglefileData (decoded as text when possible; content over 1 MB is truncated, and undecodable files are returned base64-encoded), Int and Float (returned as their numeric value), Dict (returned as its dictionary), and ArrayData (returned as its named arrays; arrays over 1000 rows along their first axis are truncated).

Parameters:

pk (int) – Primary key of the node.

Returns:

The node’s content, in a shape that depends on its type.

Return type:

dict

aiida_mcp.server.get_process(pk: int) → dict

Show details, inputs and outputs for one process node by PK.

Parameters:

pk (int) – Primary key of the process node.

Returns:

The process’s details, plus summaries of its incoming and outgoing links.

Return type:

dict

aiida_mcp.server.get_process_report(pk: int, limit: int = 100) → dict

Show the most recent log messages for one process node by PK, oldest first.

Parameters:
  • pk (int) – Primary key of the process node.

  • limit (int) – Maximum number of log entries to return (capped at 1000).

Returns:

The total number of log entries, the number returned, and the log entries themselves.

Return type:

dict

aiida_mcp.server.get_status() → dict

Report the AiiDA profile, daemon and broker status.

Returns:

Whether a profile is loaded, the daemon state, and broker connectivity.

Return type:

dict

aiida_mcp.server.list_codes(computer: str | None = None, limit: int = 20) → dict

List codes, optionally only those on one computer.

Parameters:
  • computer (str or None) – Computer label to filter by.

  • limit (int) – Maximum number of codes to return (capped at 200).

Returns:

The number of matching codes, the number returned, and a summary of each one.

Return type:

dict

aiida_mcp.server.list_computers() → dict

List all configured computers.

Returns:

The total number of computers and a summary of each one.

Return type:

dict

aiida_mcp.server.list_processes(state: str | None = None, label: str | None = None, created_after: str | None = None, limit: int = 20) → dict

List AiiDA process nodes, newest first.

Parameters:
  • state (str or None) – One of created, waiting, running, finished, excepted, killed.

  • label (str or None) – Exact process label to match.

  • created_after (str or None) – ISO date or datetime, e.g. 2026-11-01 or 2026-11-01T09:00:00.

  • limit (int) – Maximum number of processes to return (capped at 200).

Returns:

The number of matching processes, the number returned, and a summary of each one.

Return type:

dict

aiida_mcp.server.list_profiles() → dict

List all configured AiiDA profiles, showing the current and default ones.

Returns:

The name of the currently loaded profile, the default profile, and a summary of every configured profile.

Return type:

dict

aiida_mcp.server.main() → None

Parse command-line arguments and run the MCP server.

aiida_mcp.server.ping() → str

Check that the server is running.

Returns:

Always "pong".

Return type:

str

aiida_mcp.server.query_nodes(node_type: str | None = None, group: str | None = None, extra_key: str | None = None, limit: int = 20) → dict

Query nodes, newest first.

Parameters:
  • node_type (str or None) – Node type prefix, e.g. data.core.int or process.calculation. A trailing % is optional.

  • group (str or None) – Group label to restrict results to.

  • extra_key (str or None) – Only include nodes that have this extras key.

  • limit (int) – Maximum number of nodes to return (capped at 200).

Returns:

The number of matching nodes, the number returned, and a summary of each one.

Return type:

dict

aiida_mcp.server.rescan_plugins() → dict

Re-check for installed aiida_mcp.plugins entry points and register new ones.

Plugin tools are discovered from the aiida_mcp.plugins entry point group, which any installed package can declare in its own metadata. Both AiiDA’s and Python’s entry point lookups are cached for the lifetime of the server process, so a plugin package installed after the server started (with its own aiida_mcp.plugins entry point already declared in its installed metadata) is not picked up automatically. This clears those caches and registers tools for any plugin that has since become available; already-registered plugins are left alone.

Returns:

Every plugin entry point currently available, and which of those (if any) were newly registered by this call.

Return type:

dict