Nimbus BCI

nimbus-mcp

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 on public MOABB/BNCI datasets, render plots, and export BIDS — through your local Nimbus backend or the hosted deployment, with one `nimbus-mcp login`.

Docs: docs.nimbusbci.com · Overview: nimbusbci.com/mcp · Jump to Quickstart

Quickstart (hosted, recommended)

Nothing to install: point your MCP client at the hosted server https://nimbus-mcp.fly.dev/mcp. On first use your client opens a browser sign-in to Nimbus Studio (OAuth) — no token to paste.

Cursor — click the Add to Cursor button above, or put this in .cursor/mcp.json (or ~/.cursor/mcp.json):

{

"mcpServers": { "nimbus": { "url": "https://nimbus-mcp.fly.dev/mcp" } } }

Claude Code:

claude mcp add --transport http nimbus https://nimbus-mcp.fly.dev/mcp

Claude Desktop / claude.ai: Settings → Connectors → *Add custom connector* → URL https://nimbus-mcp.fly.dev/mcp. (Custom connectors may require a paid Claude plan.)

Other clients (streamable HTTP):

{

"mcpServers": { "nimbus": { "type": "http", "url": "https://nimbus-mcp.fly.dev/mcp" } } }

Headless / CI (no browser): OAuth stays the primary path, but the gateway also accepts a Nimbus API key (create one on the Studio Account page) as a Bearer header:

{

"mcpServers": { "nimbus": { "type": "http", "url": "https://nimbus-mcp.fly.dev/mcp", "headers": { "Authorization": "Bearer ${NIMBUS_TOKEN}" } } } }

claude mcp add --transport http nimbus https://nimbus-mcp.fly.dev/mcp \

--header "Authorization: Bearer $NIMBUS_TOKEN"

Try it in 60 seconds

After sign-in, paste this prompt into your agent:

Benchmark a CSP + LDA motor-imagery pipeline on BCI IV 2a (BNCI2014_001),

show me the confusion matrix, and compare the score to the leaderboard.

You should see the agent call catalog.datasets / catalog.templates, start a run with execution.run, poll execution.get, then show execution.results (accuracy / kappa), a plots.* figure and the catalog.leaderboard comparison — all on public MOABB data, no EEG device needed. The longer guided loop is in examples/demo.md.

The server also ships 5 ready-made MCP prompts (your client lists them as slash commands / prompt templates): mi_csp_lda_bci_iv_2a, compare_mi_pipelines, foundation_backbones, inspect_my_eeg and leaderboard_standing.

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:

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 locally (stdio)

Prefer running the server on your own machine (or using your local Studio desktop backend)? Sign in once, then use a secret-free config:

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

{

"mcpServers": { "nimbus": { "command": "uvx", "args": ["nimbus-mcp"] } } }

Both uvx nimbus-mcp and python -m nimbus_mcp (inside the env where it is installed) start the stdio MCP server. Agent-oriented install steps (e.g. for Cline): llms-install.md.

(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"] } } }

1. 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.

1. 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. A NIMBUS_TOKEN / NIMBUS_TOKEN_FILE token with NIMBUS_API_URL unset talks to the hosted API (https://nimbus-studio.fly.dev); set NIMBUS_API_URL to point it anywhere else.

No credential anywhere? That is the Local Free tier — it works. The server starts anonymously against the local backend (desktop app or dev backend on http://127.0.0.1:8080): templates, your own data, local execution/plots/stats, BIDS export and local-only storage need no Nimbus Studio login at all. Login is requested only at first *cloud* value — a tool that needs an identity (leaderboard submission, verified/cross-machine experiment history, hosted compute, cloud sync, collaboration) returns {ok: false, loginRequired: true, trigger, reason, howToAuthenticate} naming exactly why, instead of a blanket gate. Hosted Pro features (verified leaderboard submissions, foundation.compare, big campaigns, team features) return {ok: false, tierGate: true, requiredTier: "pro"} on free accounts; exports (BIDS etc.) are never gated at any tier. If a local call fails because no local backend/identity exists, the response is the local-mode variant of {ok: false, setupRequired: true, message, options} (start the desktop app / set a dev key — still no login). A hosted token rejected mid-session (expired or revoked) returns the classic setup shape, including how many days ago it expired.

Checking who you are

account.whoami() → {userId, email, plan: {isPro, pioneerAccess},

freeRuns: {monthlyLimit, remaining}, token: {name, kind, scopes, fullAccess, expiresAt, daysLeft} | {masked, kind, scopes, fullAccess, expiresAt, daysLeft} # gateway header token | null, 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.

Headless agents and CI (API keys)

For CI pipelines and unattended agents, mint a CI key in Nimbus Studio → Account → API tokens: choose type CI / headless, a lifetime of 90, 180 or 365 days, and pick its scopes. CI keys are a Pro feature (Pro plan or Pioneer access); Free accounts can still use personal tokens.

CI keys default to read + run; a full-access CI key is an explicit choice (the Full access checkbox, or "fullAccess": true on POST /api/me/api-tokens). Personal tokens keep the old default: no scope selected = full access, and every token minted before scopes existed keeps working unchanged. The backend enforces scopes on every request; a missing scope answers 403 nimbus.auth.token_scope_insufficient. account.whoami and nimbus-mcp status show the key's kind, scopes and days left.

Store the key as a CI secret and pass it as NIMBUS_TOKEN (no NIMBUS_API_URL needed — a token defaults to hosted Nimbus). GitHub Actions example:

- name: Nimbus smoke run

env: NIMBUS_TOKEN: ${{ secrets.NIMBUS_CI_KEY }} run: | pipx install nimbus-mcp nimbus-mcp status # fails fast if the key is expired or revoked

Or call the hosted gate