eLabFTW MCP

Standalone Model Context Protocol server for eLabFTW — 41 tools, pure Python, MCP protocol revision 2026-07-28 (stateless) with older handshakes still served. Single-user (stdio) and multi-user hosted mode (register page → personal URL with scoped token).

No R runtime, no external tool library: everything talks to the eLabFTW REST API v2 directly.

Credits

The tool surface, parameter names, validation rules and the safety rails (append-only body updates, provenance blocks, dry-run link operations) are a faithful port of

Marvin Luepke — elabR / elabrmcp

which implemented the same 41 tools in R on top of mcptools/`ellmer. That implementation is the reference this port was written against, and its documented behaviour is what the tests assert. Thank you — this would have been a much worse server without it.

Also derived from that work: the hosted mode's feature set (register flow, profile presets, per-token tool scope, audit log), which previously lived in the unified-researchdata-mcp deployment.

Related MCP server: protocol-mcp

Tools (41)

Write tools honour the profile of the token (r read-only, h hybrid, f full) and the features.write_* switches in the config; destructive operations require an explicit confirmation argument.

Install

pip install .                 # or: uv pip install .

Requires Python ≥ 3.10 and an eLabFTW API key (eLabFTW → Account → API keys).

Local (stdio) usage

{
  "mcpServers": {
    "elabftw": {
      "command": "elabftw-mcp",
      "env": {
        "ELABFTW_BASE_URL": "https://elntest.ub.tum.de",
        "ELABFTW_API_KEY": "your-key"
      }
    }
  }
}

Or against any HTTP client: elabftw-mcp --transport streamable-http --port 8081 (stateless by default, --stateful for session-based clients, --json-response if the client cannot read SSE).

Hosted (multi-user) usage

export MCP_JWT_SECRET="$(python -c 'import base64,os;print(base64.urlsafe_b64encode(os.urandom(32)).decode())')"
elabftw-mcp --hosted --host 0.0.0.0 --port 8081

• /register — enter instance URL + API key, pick a profile and the tools to expose

• /mcp?token=… — the MCP endpoint for the issued personal URL

• /status — service and protocol info

• audit log (JSONL), registration rate limit, X-Forwarded-Proto aware

Tokens are HMAC-signed and carry the instance URL, the API key, the profile and the tool allow-list; keys are never stored server-side. Requests without a valid token get 401; tools outside a token's scope are refused with -32601.

Configuration

config.example.yml → config.yml (path via ELABFTW_MCP_CONFIG). Everything can be overridden by environment variables: ELABFTW_BASE_URL, ELABFTW_API_KEY, ELABFTW_MCP_AI_MODEL, ELABFTW_MCP_AI_KEY, ELABFTW_MCP_AI_BASE_URL, ELABFTW_MCP_RATE_LIMIT, MCP_JWT_SECRET, MCP_TOKEN_EXPIRY_DAYS, ELABFTW_MCP_AUDIT_LOG.

features:
  write_enabled: true        # master switch for every write tool
  write_create: true         # create_experiment / create_item / …
  write_update: true         # body / field / metadata updates
  allow_body_overwrite: true # otherwise only append mode is allowed
  ai_review: true            # review_experiment etc.
  cache_ttl_seconds: 300     # cache for team catalogues and /users/me

AI tools

review_experiment, suggest_tags and suggest_metadata call an OpenAI-compatible chat-completions endpoint (ai.base_url, ai.model, ai.api_key). Without a key they answer with the upstream placeholder wording instead of failing — the response contract (trace_id, entity_type, entity_id, suggestions, status) stays identical either way.

Tests

python tests/test_api_contract.py     # offline: request shapes vs. the OpenAPI spec
python tests/test_tools_offline.py    # offline: all 41 tools against a stub eLabFTW
python tests/test_transports.py       # offline: stdio + stateless HTTP, real MCP client
python tests/test_ai_tools.py         # offline: AI tools vs. a local LLM stub (no quota spent)
python tests/test_ai_tools.py --live  # live instance + local LLM stub
python tests/test_live_tools.py       # live: all 41 tools against a real instance
python tests/test_proxy_live.py       # live: register flow, scope, protocol eras

For a running deployment there are two checks that need nothing but a URL:

python tests/diagnostics/deployed_e2e.py    # one endpoint: register, 41 tools, read + write + cleanup
python3 tests/diagnostics/service_sweep.py  # the whole host: web hosts, register pages, /el, /dt, /nm

Live suites read the key from ../.elab_key (never printed), tag everything they create as elabmcp-test-<timestamp> and delete it again. tests/diagnostics/ holds the small probes used to pin down the API behaviour on a new instance (step fields, link direction, metadata payload).

Status of the last full run (eLabFTW 6.0.1, MCP Python SDK 2.2.0):

API notes (measured against a running instance, not just the spec)

Response statuses used by the write tools: created, updated, deleted, uploaded, linked, already_linked, would_link, unlinked, already_absent, would_unlink, ok, partial — the same vocabulary across all write tools.

Relation to the previous /el deployment

Measured against the running R-based service (researchmcp.duckdns.org/el, reproduced by tests/diagnostics/compare_with_deployed.py): the tool surface is identical — 41 tools on both sides, none missing, none extra — and the same entities and ids come back (categories, statuses and user info 100% identical, get_experiment 81%).

Deliberate differences:

Only /el (proxy + R worker) is replaced. /nm (NOMAD MCP), /dt (DataTagger MCP), the eLabFTW instance, the databases, Caddy and the two Streamlit apps keep running untouched.

Documented differences from the upstream R implementation

License

MIT, see LICENSE.

This server is a rewrite of Marvin Luepke's elabMCP R server and its elabR library, both MIT licensed. The tool surface, the response shapes and the runtime quirks documented below follow those sources; the credits are in the section above.