nimbus-mcp

<!-- mcp-name: io.github.nimbusbci/nimbus-mcp --> <!-- smithery badge: their /badge/ endpoint 500s platform-wide (2026-10-07); shields.io image + link keeps the badge rendering -->

MCP server that lets AI agents (Claude Code, Cursor, Claude Desktop) build, validate, run, and analyze Nimbus BCI pipelines — upload their own EEG data, persist pipelines into studio projects, run multi-configuration experiment campaigns, watch live EEG sessions, and (explicitly confirmed) start live streaming — through your local Nimbus backend or the hosted deployment, with one nimbus-mcp login.

Why nimbus-mcp (October 2026 field)

The BCI-MCP niche grew four other servers in 2026. They are honest, focused tools — and each covers a slice of what nimbus-mcp does end-to-end:

| Capability | nimbus-mcp | bci-mcp | eeg-mcp | mne-mcp | ephys-mcp | |---|---|---|---|---|---| | Build + validate + run BCI pipelines | ✅ 60 tools | — | — | — | — | | Train on real data (MOABB packs, uploads) | ✅ | — | — | file I/O only | NWB/DANDI | | Bring-your-own model code (python_model) | ✅ local + cloud sandbox | — | — | — | — | | Benchmark leaderboard + server-side LOSO scoring | ✅ | — | — | — | — | | Agent-visible figures (PNG content blocks) | ✅ plots.* | — | — | ✅ | ✅ | | Live hardware sessions on a human | ✅ confirm-gated | ✅ | ✅ | — | — | | Modelless live band powers (focus/relaxation) | ✅ stream.telemetry | ✅ | ✅ | — | — | | Guided subject calibration | ✅ calibration.* | — | — | — | — | | Neurofeedback protocol sessions | ✅ protocol.* | — | — | — | — | | BIDS export (sha256 manifests) | ✅ bids.* | — | — | — | — | | Cluster-aware group statistics | ✅ stats.grouped | — | — | — | partial | | Transport | stdio + hosted HTTP gateway | stdio + HTTP | stdio | stdio | stdio | | Validation evidence | arXiv:2610.13894 — parity study, 3 datasets / 6 pipelines / 2 protocols | band-ratio heuristics | — | — | — |

Scope honesty (deliberate non-goals): no stimulation output (eeg-mcp's triple-interlocked send_stim_event is genuinely novel; we don't drive stimulators), no spike/ephys data (ephys-mcp covers intracortical recording — different data plane), no source localization / full MNE parity (mne-mcp is a deep offline MNE wrapper; plots.* covers the figures agents need on Nimbus data).

Install

pip install nimbus-mcp   # or: uvx nimbus-mcp

(Also installable from the repo: pip install -e nimbus-studio/mcp.)

Zero-hardware demo: examples/demo.md — a copy-paste agent prompt that runs the whole loop (explore → inspect → figures → train → confusion figure → leaderboard → stats) on public MOABB data, no device.

Authentication

Three ways to give the server a credential — tried in this order at startup:

1. nimbus-mcp login (recommended — hosted API, no token pasting). A device-code login: the command prints a URL and an 8-character code, opens your browser, you approve in Nimbus Studio, and the minted token is stored at ~/.nimbus/credentials.json (0600) and picked up automatically on every future start.

   nimbus-mcp login     # options: --api-url URL, --ttl-days 7..90, --name NAME
   nimbus-mcp status    # doctor: credential source, plan, quota, days-to-expiry, live probe
   nimbus-mcp logout    # remove the stored credential
   

   After a login, MCP client configs need no secret at all:

   {
     "mcpServers": {
       "nimbus": {
         "command": "uvx",
         "args": ["nimbus-mcp"],
         "env": { "NIMBUS_API_URL": "https://nimbus-studio.fly.dev" }
       }
     }
   }
   

2. Desktop app — zero config. Just have the Nimbus Studio desktop app running: its local key file is auto-discovered (macOS ~/Library/Application Support/Nimbus Studio/mcp-key.json, Linux ~/.config/Nimbus Studio/…, Windows %APPDATA%\Nimbus Studio\…) and the server talks to the local backend at http://127.0.0.1:8080. Nothing to paste or configure.

3. Environment variables (advanced / CI). NIMBUS_TOKEN (a hosted API token nimb_… minted in Nimbus Studio → Account → API tokens) or NIMBUS_TOKEN_FILE (a 0600 JSON file {"token": "…"} — keeps the secret out of process env and MCP configs), or the local pair NIMBUS_MCP_KEY / NIMBUS_MCP_KEY_FILE (must match MCP_LOCAL_KEY on a local backend — see below). Explicit env always beats files on disk.

No credential anywhere? The server still starts — in setup mode. Every tool call returns {ok: false, setupRequired: true, message, options} with the three paths above, so your agent walks you through onboarding instead of the server crashing. A hosted token rejected mid-session (expired or revoked) returns the same shape, including how many days ago it expired and a nimbus-mcp login first option.

Checking who you are

account.whoami() → {userId, email, plan: {isPro, pioneerAccess},
            freeRuns: {monthlyLimit, remaining},
            token: {name, expiresAt, daysLeft} | {masked} | null,  # {masked} = gateway header token
            source}                                      # store | env | token_file | header | …

Call account.whoami() from the agent to see the account, plan, this month's free-run quota, and (in token mode) the token's days-to-expiry; nimbus-mcp status is the terminal equivalent with a live backend probe.

What a hosted token means

• The token IS you. Requests run under your account: executions appear in your studio history and your plan's quotas and limits apply — there is no separate agent allowance. When the free monthly quota is exhausted, run errors carry the upgrade link https://studio.nimbusbci.com/pricing?reason=mcp-quota.
• CPU-only in v0.4. Token-authenticated runs do not hydrate cloud GPUs.
• Rotation. Tokens live at most 90 days (30 by default). Plan changes are snapshotted at mint time — after an upgrade, re-login (or revoke and re-create the token) to pick up the new plan. An expired token surfaces as setup guidance with the day count, not a dead end.

Requirements (local mode)

• A Nimbus backend running locally: the desktop app, or the dev server (cd nimbus-studio/backend-py && python -m nimbus_backend.server.app) with DEBUG=1.
• The backend started with MCP_LOCAL_KEY=<some-secret> (never set this on Fly — it is refused there).
• Desktop app users: open Settings → MCP & Agents — no manual key setup (the app creates the key, injects it into its backend, and hands you copy-ready configs).

No desktop app required. Acquisition is fully in-backend: a headless local backend + nimbus-mcp can drive real hardware (BrainFlow boards, BrainBit over BLE, LSL, PiEEG) and synthetic boards, with zero Electron:

git clone <this repo> && cd NimbusStudio/nimbus-studio/backend-py
pip install -e ".[streaming]"            # brainflow + pyneurosdk2 + pylsl extras
export DESKTOP_LOCAL_BACKEND=true MCP_LOCAL_KEY=<secret> MCP_LOCAL_USER_ID=user_…
python -m nimbus_backend.server.app      # loopback backend with device radios
# another shell: nimbus-mcp against http://127.0.0.1:8080 with NIMBUS_MCP_KEY=<secret>

The same stream.start → stream.telemetry flow then works with OR without a trained model (modelless streams report live signal quality + focus/relaxation indicators).

Configure the backend

Desktop/dev env (e.g. backend-py/data/.env or the dev shell):

MCP_LOCAL_KEY=choose-a-long-random-string
MCP_LOCAL_USER_ID=user_your_clerk_user_id
DEBUG=1   # dev server only; the desktop app qualifies automatically

MCP_LOCAL_USER_ID sets the principal the MCP key authenticates as. Set it to your own Clerk user id (user_…) so everything the agent creates — projects, saved pipelines, executions — appears in your studio UI as yours. Pick one owner and stick with it: switching the id mid-life splits ownership of agent-created work across two principals, and neither identity then sees the whole history.

Watchdog default: streaming sessions started through MCP are auto-stopped after 15 minutes with no one watching (every stream.status / stream.telemetry poll resets the timer). Pass idle_timeout_sec=0 to stream.start to disable it for a session.

When enabling MCP_LOCAL_KEY on a machine connected to an untrusted network, also set HOST=127.0.0.1 on the backend. The 0.0.0.0 default (settings.host) applies to the bare dev server (python -m nimbus_backend.server.app), so with it the key would otherwise be accepted from the LAN; backend-py/scripts/run_server.py already defaults to 127.0.0.1, and the desktop app pins loopback itself.

Run the server

cd nimbus-studio/mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[test]"
NIMBUS_MCP_KEY=choose-a-long-random-string python -m nimbus_mcp

Env vars: NIMBUS_API_URL (default http://127.0.0.1:8080, or the store's api_url after a login), NIMBUS_TOKEN / NIMBUS_TOKEN_FILE (hosted API token — see Authentication), NIMBUS_MCP_KEY (must match MCP_LOCAL_KEY), NIMBUS_MCP_KEY_FILE (path to a 0600 JSON file {"key": "…"} — the desktop app's one-click MCP setup writes it; consulted only when NIMBUS_MCP_KEY is unset), NIMBUS_EXPORT_DIR (default ~/nimbus-exports). With none of the token/key vars set, the login store and then the desktop key file are auto-discovered; with nothing found, the server runs in setup mode (every tool returns onboarding guidance).

Hosted gateway (streamable HTTP)

nimbus-mcp serve runs the same 60 tools over streamable HTTP instead of stdio — for remote MCP clients, registries (Smithery lists URL-based servers), and browser-side clients:

nimbus-mcp serve --port 8080   # env: NIMBUS_MCP_HOST/PORT/PATH

The gateway binds 127.0.0.1 by default — exposing it (--host 0.0.0.0) is explicit opt-in; combine that with the per-request tokens below (the gateway itself holds no credential to gate access with).

The gateway holds no credential itself: each request's Nimbus API token arrives as a header, so one shared deployment serves many users as themselves. Calls without a header get setup guidance (add the header, or install locally via uvx).

{
  "mcpServers": {
    "nimbus": {
      "type": "http",
      "url": "https://nimbus-mcp.fly.dev/mcp",
      "headers": { "X-Nimbus-Token": "nimb_…  (Account → API tokens)" }
    }
  }
}

(A gateway started with NIMBUS_TOKEN in the environment uses it as the fallback for headerless calls — single-tenant self-hosting.)

Claude Code

# --env flags go BEFORE the -- separator (everything after it is the literal
# server command, so the after-form would feed --env to python/uvx):
claude mcp add nimbus --env NIMBUS_MCP_KEY=choose-a-long-random-string \
  -- <path-to-mcp-venv>/bin/python -m nimbus_mcp

Cursor / Claude Desktop (stdio)

{
  "mcpServers": {
    "nimbus": {
      "command": "<path-to-mcp-venv>/bin/python",
      "args": ["-m", "nimbus_mcp"],
      "env": { "NIMBUS_MCP_KEY": "choose-a-long-random-string" }
    }
  }
}

Tools (60)

Auth: account.whoami (account, plan, quota, token expiry) Discovery: catalog.nodes, catalog.node_schema, catalog.templates, catalog.template, catalog.datasets, catalog.leaderboard Data: data.upload, data.delete_upload (needs confirm=true) Inspect: data.inspect_dataset, data.inspect_file (EDA: channels, class balance, band powers, PSD) Build: pipeline.validate, pipeline.validate_node Run: execution.run (non-blo