Nimbus BCI

nimbus-mcp

MCP 服务可让 AI Agent（Claude Code、Cursor、Claude Desktop）构建、验证、 运行和分析 Nimbus BCI 工作流 — 上传自己的 EEG 数据，将工作流持久化到工作室项目中， 运行多配置实验活动，监控实时 EEG 会话，以及（经明确确认后）启动实时流式传输 — 可连接本地 Nimbus 后端，或通过一次 nimbus-mcp login 登录托管部署。

为什么选择 nimbus-mcp（2026 年 10 月现状）

BCI-MCP 领域在 2026 年新增了其他四个 MCP 服务。它们都是专注于特定领域的实用工具 — 各自覆盖了 nimbus-mcp 端到端功能的一部分：

能力	nimbus-mcp	bci-mcp	eeg-mcp	mne-mcp	ephys-mcp
构建 + 验证 + 运行 BCI 工作流	✅ 63 个工具	—	—	—	—
使用真实数据训练（MOABB 数据包、上传数据）	✅	—	—	仅文件 I/O	NWB/DANDI
使用自带的模型代码（python_model）	✅ 本地 + 云沙箱	—	—	—	—
基准排行榜 + 服务端 LOSO 评分	✅	—	—	—	—
Agent 可见的图形（PNG 内容块）	✅ plots.*	—	—	✅	✅
人体实时硬件会话	✅ 需确认	✅	✅	—	—
无模型实时频带功率（专注/放松）	✅ stream.telemetry	✅	✅	—	—
引导式受试者校准	✅ calibration.*	—	—	—	—
神经反馈协议会话	✅ protocol.*	—	—	—	—
BIDS 导出（sha256 清单）	✅ bids.*	—	—	—	—
考虑簇结构的组统计	✅ stats.grouped	—	—	—	部分支持
传输方式	stdio + 托管 HTTP 网关	stdio + HTTP	stdio	stdio	stdio
验证依据	arXiv:2610.13894 — 一致性研究，3 个数据集 / 6 个工作流 / 2 个协议	频带比值启发式方法	—	—	—

范围说明（有意不覆盖的目标）：不提供刺激输出（eeg-mcp 的三重互锁 send_stim_event 确实很新颖；我们不驱动刺激器），不处理尖峰/电生理数据（ephys-mcp 覆盖皮层内记录 — 属于不同的数据平面），不提供源定位 / 完整 MNE 一致性（mne-mcp 是深度离线 MNE 封装；plots.* 则提供 Agent 在 Nimbus 数据上所需的图形）。

安装

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

（也可以从仓库安装：pip install -e nimbus-studio/mcp。）

零硬件演示：examples/demo.md — 一段可复制粘贴的 Agent 提示词，可在公开 MOABB 数据上运行完整流程（探索 → 检查 → 图形 → 训练 → 混淆图 → 排行榜 → 统计），无需设备。

身份验证

启动时按以下顺序尝试通过三种方式为服务提供凭据：

1. nimbus-mcp login（推荐——托管 API，无需粘贴令牌）。 通过设备代码登录：命令会打印一个 URL 和一个 8 位代码，打开浏览器后，你在 Nimbus Studio 中批准登录，生成的令牌会存储在 ~/.nimbus/credentials.json（0600）中，并在之后每次启动时自动读取。

   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
   

登录后，MCP 客户端配置无需任何密钥：

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

2. 桌面应用——无需配置。 只需运行 Nimbus Studio 桌面应用：系统会自动发现本地密钥文件（macOS ~/Library/Application Support/Nimbus Studio/mcp-key.json、Linux ~/.config/Nimbus Studio/…、Windows %APPDATA%\Nimbus Studio\…），服务会连接到本地后端 http://127.0.0.1:8080。无需粘贴或配置任何内容。

3. 环境变量（高级 / CI）。 NIMBUS_TOKEN（在 Nimbus Studio → Account → API tokens 中生成的托管 API 令牌 nimb_…）或 NIMBUS_TOKEN_FILE（内容为 {"token": "…"} 的 0600 JSON 文件——可避免将密钥放在进程环境变量和 MCP 配置中），或本地密钥对 NIMBUS_MCP_KEY / NIMBUS_MCP_KEY_FILE（必须与本地后端上的 MCP_LOCAL_KEY 匹配——见下文）。显式设置的环境变量始终优先于磁盘上的文件。若未设置 NIMBUS_API_URL，NIMBUS_TOKEN / NIMBUS_TOKEN_FILE 令牌会连接到托管 API（https://nimbus-studio.fly.dev）；设置 NIMBUS_API_URL 可将其指向其他地址。

完全没有凭据？ 这就是 Local Free 层级——它可以正常使用。服务会以匿名方式连接本地后端（桌面应用或运行在 http://127.0.0.1:8080 的开发后端）：模板、你自己的数据、本地执行/绘图/统计、BIDS 导出和仅本地存储，完全无需登录 Nimbus Studio。只有在首次需要使用云端功能时才会要求登录——需要身份的工具（提交排行榜、已验证/跨机器实验历史、托管计算、云同步、协作）会返回 {ok: false, loginRequired: true, trigger, reason, howToAuthenticate}，明确说明具体原因，而不是一概拦截。托管 Pro 功能（已验证的排行榜提交、foundation.compare、大型活动、团队功能）在免费账户上会返回 {ok: false, tierGate: true, requiredTier: "pro"}；任何层级的导出（BIDS 等）都不会受到限制。如果本地调用因本地后端或身份不存在而失败，响应会采用本地模式下的 {ok: false, setupRequired: true, message, options} 形式（启动桌面应用 / 设置开发密钥——仍然无需登录）。如果托管令牌在会话期间被拒绝（过期或撤销），则会返回经典设置提示，其中包括令牌过期了多少天。

查看你的身份

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 | …

在 Agent 中调用 account.whoami()，即可查看账户、套餐、本月免费运行配额，以及（令牌模式下）令牌距离过期的天数；nimbus-mcp status 是对应的终端命令，会实时探测后端。

托管令牌的含义

• 令牌代表的就是你。 请求会以你的账户身份运行：执行记录会显示在你的 Studio 历史记录中，且适用你套餐的配额和限制——不存在单独的 Agent 配额。免费月度配额用尽后，运行错误会附带升级链接 https://studio.nimbusbci.com/pricing?reason=mcp-quota。
• v0.4 中仅支持 CPU。 通过令牌身份验证的运行不会启用云端 GPU。
• 轮换。 令牌的有效期最长为 90 天（默认 30 天）。套餐变更会在生成令牌时记录快照——升级后，请重新登录（或撤销并重新创建令牌）以应用新套餐。令牌过期时会显示包含过期天数的设置指引，而不会让你无从处理。

无头 Agent 和 CI（API 密钥）

对于 CI 流水线和无人值守的 Agent，请在 Nimbus Studio → Account → API tokens 中创建 CI 密钥：选择类型 CI / headless，设置 90、180 或 365 天的有效期，并选择其作用域。CI 密钥是 Pro 功能（Pro 套餐或 Pioneer 权限）；Free 账户仍可使用个人令牌。

作用域	允许的操作
read	GET/list/describe，以及仅进行计算的 POST（validate、plots、stats、export）
run	启动／取消执行和实验（会消耗你的配额）
write	创建／更新／删除项目、流水线、上传内容和设置
leaderboard:submit	提交排行榜结果

CI 密钥默认具有 read + run 作用域；选择完全访问权限的 CI 密钥需要显式操作（勾选 Full access，或在 POST /api/me/api-tokens 中设置 "fullAccess": true）。个人令牌保留原有默认行为：未选择作用域 = 完全访问权限；所有在作用域功能推出前创建的令牌仍可照常使用。后端会对每个请求强制执行作用域检查；缺少所需作用域时会返回 403 nimbus.auth.token_scope_insufficient。account.whoami 和 nimbus-mcp status 会显示密钥类型、作用域和剩余天数。

将密钥保存为 CI 密钥，并通过 NIMBUS_TOKEN 传入（无需设置 NIMBUS_API_URL——令牌默认连接托管版 Nimbus）。GitHub Actions 示例：

- 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

或者，调用托管网关 https://nimbus-mcp.fly.dev/mcp，并附上请求头 Authorization: Bearer $NIMBUS_TOKEN。请在密钥过期前轮换（Account 页面会标记将在 14 天内过期的密钥），若密钥泄露，请立即撤销——撤销会在下一个请求时生效。

API 密钥的套餐和限制：

• 套餐会实时重新检查：每个使用 API 密钥发出的请求都会查询你当前的 Clerk Billing 套餐（缓存约一分钟），因此取消 Pro 套餐也会移除现有密钥的 Pro 功能，而不仅仅影响新密钥。
• 如果 CI 密钥的所有者不再拥有 Pro 套餐，每个请求都会被拒绝，并返回 403 nimbus.auth.ci_key_requires_pro。重新订阅后即可恢复使用（无需重新创建密钥）；否则，请撤销该密钥并改用个人令牌。
• 最多可拥有 20 个有效（未撤销、未过期）API 令牌；再创建一个会返回 409 nimbus.me.api_token_limit_reached。通过 MCP OAuth 登录创建的令牌不计入此限制。

隐私与遥测

本地 Free 模式无需账户，默认不会向外发送任何信息。匿名且不包含内容的使用遥测（工具名称、成功／失败状态和错误代码、耗时区间——绝不包含你的数据、文件路径或代码）为选择加入：全新安装后，你会在第一次工具响应中收到一次询问；你也可以随时使用 nimbus-mcp telemetry on|off|status（或 NIMBUS_MCP_TELEMETRY=on|off）控制遥测。关闭遥测后不会产生任何遥测网络请求，所有本地功能仍可正常使用。完整声明见：PRIVACY.md。启动时会静默检查 PyPI 版本（缓存 24 小时；当前版本或离线时不显示提示）；如果你的客户端落后于托管网关支持的功能范围，工具响应中会一次性附加 versionNotice。

要求（本地模式）

• 本地运行的 Nimbus 后端：桌面应用，或开发服务器（cd nimbus-studio/backend-py && python -m nimbus_backend.server.app），并设置 DEBUG=1。
• 后端启动时设置 MCP_LOCAL_KEY=<some-secret>（请勿在 Fly 上设置此项——在那里会被拒绝）。
• 桌面应用用户：打开 Settings → MCP & Agents——无需手动设置密钥（应用会创建密钥、将其注入后端，并提供可直接复制的配置）。

无需桌面应用。 数据采集完全在后端进行：无头本地后端 + nimbus-mcp 即可驱动真实硬件（BrainFlow 电路板、通过 BLE 连接的 BrainBit、LSL、PiEEG）和模拟电路板，无需 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>

随后，相同的 stream.start → stream.telemetry 流程无论是否使用训练好的模型都可正常工作（无模型的流会报告实时信号质量以及专注度／放松度指标）。

配置后端

桌面端／开发环境（例如 backend-py/data/.env 或开发 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 用于设置 MCP 密钥所认证的主体。将其设为你自己的 Clerk 用户 ID（user_…），这样 Agent 创建的所有内容——项目、已保存的流水线、执行记录——都会在你的工作室 UI 中显示为你所有。选定一个所有者后请始终保持一致：中途切换 ID 会将 Agent 创建的内容拆分到两个主体名下，两个身份都无法看到完整历史记录。

监视器默认设置：通过 MCP 启动的流式会话在无人查看 15 分钟后会自动停止（每次 stream.status／stream.telemetry 轮询都会重置计时器）。对 stream.start 传入 idle_timeout_sec=0 可为该会话停用此功能。

在连接到不受信任网络的计算机上启用 MCP_LOCAL_KEY 时，也要在后端设置 HOST=127.0.0.1。默认值 0.0.0.0（settings.host）适用于裸开发服务器（python -m nimbus_backend.server.app），否则该密钥也会接受来自局域网的请求；backend-py/scripts/run_server.py 已默认使用 127.0.0.1，桌面应用也会自行固定为回环地址。

运行服务

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

环境变量：NIMBUS_API_URL（设置后始终优先；否则，登录后使用存储中的 api_url，对于 NIMBUS_TOKEN／NIMBUS_TOKEN_FILE 令牌使用 https://nimbus-studio.fly.dev，其他情况使用 http://127.0.0.1:8080）、NIMBUS_TOKEN／NIMBUS_TOKEN_FILE（托管 API 令牌——请参阅 身份验证）、NIMBUS_MCP_KEY（必须与 MCP_LOCAL_KEY 匹配）、NIMBUS_MCP_KEY_FILE（0600 JSON 文件 {"key": "…"} 的路径——桌面应用的一键 MCP 设置会写入此文件；仅在未设置 NIMBUS_MCP_KEY 时读取）、NIMBUS_EXPORT_DIR（默认值为 ~/nimbus-exports）。未设置任何令牌／密钥变量时，会自动查找登录存储，然后查找桌面密钥文件；如果都未找到，服务将以设置模式运行（每个工具都会返回入门指南）。

托管网关（可流式传输的 HTTP）

nimbus-mcp serve 通过可流式传输的 HTTP 而非 stdio 运行相同的 63 个工具，适用于远程 MCP 客户端、注册表（Smithery 会列出基于 URL 的服务）以及浏览器端客户端：

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

网关默认绑定到 127.0.0.1——公开网关（--host 0.0.0.0）需要明确选择启用；请将其与下文介绍的逐请求令牌结合使用（网关本身不持有可用于控制访问的凭据）。

网关本身不持有任何凭据：每个请求的 Nimbus API 令牌都会通过标头发送，因此一个共享部署可让多个用户各自以自己的身份使用。没有标头的调用会获得设置指南（添加标头，或通过 uvx 在本地安装）。

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

（在环境中设置了 NIMBUS_TOKEN 后启动的网关会将其用作无标头调用的后备令牌——适用于单租户自托管。）

OAuth 登录（可选，NIMBUS_MCP_OAUTH=1）

设置 NIMBUS_MCP_OAUTH=1 后，网关也会成为 OAuth 2.1 授权服务器（MCP 授权规范），因此 Claude 和 Cursor 等客户端只需使用 URL 即可连接，无需粘贴令牌：

• /.well-known/oauth-protected-resource/mcp 和 /.well-known/oauth-authorization-server 元数据；
• 动态客户端注册（/register，由后端存储）；
• /authorize（PKCE S256）会将浏览器带到 Studio /mcp/authorize，用户可在此登录并选择允许或拒绝；
• /token 会将授权码交换为普通的 nimb_ 令牌（有效期 30 天，无 刷新令牌；作用域为 read、run、write、leaderboard:submit，或在请求全部/未指定作用域时授予 完整访问权限）。对同一客户端重新授权会撤销该客户端之前的令牌，且所有 OAuth 令牌都会列在“账户 → API 令牌”下（并可撤销）。

启用此标志后，不带令牌的请求会收到规范规定的 401 响应，其中包含 WWW-Authenticate: Bearer resource_metadata=… 标头（这会启动 客户端的登录流程），因此不再公开不带标头的 tools/list。现有的 X-Nimbus-Token / Authorization: Bearer nimb_… 标头仍可使用。

变量	位置	含义
NIMBUS_MCP_OAUTH	gateway	设为 1 可启用 OAuth（默认关闭）
MCP_OAUTH_GATEWAY_SECRET	gateway 和 backend	用于仅限网关的后端路由以及签署授权请求的共享密钥（≥ 32 个字符）
NIMBUS_MCP_PUBLIC_URL	gateway	发行方 / 公共基 URL（默认 https://nimbus-mcp.fly.dev；除回环地址外必须使用 HTTPS）
NIMBUS_STUDIO_URL	gateway	/mcp/authorize 所在的位置（默认 https://studio.nimbusbci.com）
NIMBUS_API_URL	gateway	后端基 URL

在 Fly 上：对网关应用运行 fly secrets set MCP_OAUTH_GATEWAY_SECRET=… NIMBUS_MCP_OAUTH=1，并在后端设置相同的 MCP_OAUTH_GATEWAY_SECRET。如果未设置密钥，后端会对 OAuth 路由返回 503 nimbus.mcp.oauth_not_configured。

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

工具（63）

身份验证：account.whoami（账户、套餐、配额、令牌过期时间） 发现：catalog.nodes、catalog.node_schema、catalog.templates、catalog.template、catalog.datasets、catalog.leaderboard 数据：data.upload、data.delete_upload（需要 confirm=true） 检查：data.inspect_dataset、data.inspect_file（EDA：通道、类别平衡、频带功率、PSD） 构建：pipeline.validate、pipeline.validate_node 运行：execution.run（非阻塞）、execution.get、execution.list、execution.results、execution.cancel、execution.delete（需要 confirm=true）

运行摘要（execution.get / execution.list）包含两个数据集字段：dataset 是人类可读的显示标签（例如 BCIIV2a），datasetId 是目录 ID（例如 BNCI2014_001），其他工具可接受此 ID（data.inspect_dataset、图中的 public_data.dataset）。title 是 Studio 中显示的运行名称。 实验活动：experiment.run（非阻塞，1-25 次按节奏执行的运行）、experiment.get、experiment.delete（需要 confirm=true） 产物：execution.artifacts、execution.download_artifact、pipeline.export 实时：device.list、device.test、stream.start（需要 confirm=true）， stream.status、stream.telemetry、stream.stop 校准：calibration.start（需要 confirm=true）、calibration.status、 calibration.pause、calibration.resume、calibration.train 神经反馈协议：protocol.validate/protocol.save（带版本的规范）， protocol.start_assignment（需确认；模拟源免费，实时硬件需 Pro）， protocol.session_status/pause/resume/stop、protocol.export_stats （配对的前后测统计 + 图表 + CSV） 项目：project.create、project.list、project.save、project.load、project.rename、project.delete（需要 confirm=true） Python：python.validate（对 BYO 模型代码进行静态契约检查 — 不执行代码） 排行榜：leaderboard.submit（BYO python_model → 服务端 LOSO 评分， 202 + submissionId；track="pretrained_few_trial" = 效率赛道： LOSO 最多 100 次试验，torch 代码必须声明 PARAMS_TRAINED）， leaderboard.status（查询单次提交状态，仅限所有者）， leaderboard.mine（你的提交，按最新优先排序） BIDS：bids.export_dataset（打包 / 上传 / 录制 → BIDS 布局 zip； 连续数据 → BIDS-raw，分段数据 → BIDS-derivatives）、bids.export_execution （结果包：指标、participants.tsv、协议、pipeline 快照） 图表：plots.confusion、plots.dataset（psd / topomap / bandpower / spectrogram）、plots.erp（按类别绘制蝶形图）、plots.leaderboard（CI 须状条，突出显示 BYO；track=pretrained_few_trial 会并排叠加经典 LOSO 基线）— 助手可查看的 PNG 图表 统计：stats.grouped（跨运行、按受试者汇总且考虑聚类的准确率： t 区间 + 与随机水平比较的 t 检验）

不确定要构建哪种 pipeline？catalog.leaderboard() 会按规范的 within_session 协议，针对每个数据集对经过基准测试的 pipeline 排名（按 meanAccuracyPct 降序，显示 95% CI）—— Agent 会据此选择排名靠前的模板，并通过 catalog.template(pipelineId) 获取最佳模板。

先查看数据（以及结果）

在构建任何工作流之前，Agent 可以先查看数据：通道、采样率、试验/类别分布、各通道的 µV 统计数据、标准频带功率和 PSD 概览——无论是公开数据集还是磁盘上的文件。

“在选择工作流之前，先检查 BNCI2014_001 的受试者 S01。”

data.inspect_dataset(dataset="BNCI2014_001", subject="S01", mode="all")
# → {channels: {count: 22, names: [...], flatlined: []}, samplingRate: 250,
#    trials: {count: 288, classLabels: [...], classCounts: {...}},
#    channelStats: [...], bandPowers: {...}, psd: {...},
#    computedFrom: {nSamples: ..., sampleStrategy: "stratified_sample_seed42_4_of_20"}}

subject 为必填项（例如 "S01"；通过 catalog.datasets 获取列表），逗号分隔的列表（如 "S01,S03"）会加载一个队列；mode 可设为 training | evaluation | all。

文件也适用相同的方式：data.inspect_file 会根据路径形式选择数据源。绝对路径会从磁盘读取文件（仅限本地后端——桌面应用 / MCP 本地模式：无需上传，数据不会离开设备）；相对路径——即 data.upload 返回的路径——则用于描述已上传的文件，适用于任何后端（托管或本地）：

“查看 ~/recordings/session-01.edf，告诉我电极布局是否合理。”

data.inspect_file(path="/Users/you/recordings/session-01.edf")  # absolute → local file
data.inspect_file(path="uploads/<user>/session-01.edf")  # data.upload path → upload
data.inspect_file(path="uploads/<user>/eeg.csv", sampling_rate=250.0)  # CSV/TSV/TXT need a rate

CSV/TSV/TXT 不包含采样率，因此必须为其指定 sampling_rate（Hz）：如果未指定，工具会立即失败并返回 nimbus.mcp.sampling_rate_required，且不会发出任何请求。

在托管后端上，绝对路径会被拒绝——此时 data.inspect_file 会提供指引（通过 data.upload 上传文件并传入返回的路径，或将服务指向本地后端），而不是让你陷入死路。

为何要先检查：类别分布决定分层方式（类别不平衡会导致准确率偏差），而且通道信号平直意味着电极布局/参考电极可能有问题，应在训练前修复。还需注意单位：加载器默认假设单位为伏特——以 µV 为单位的 CSV 读入后数值会大 1e6 倍；必要时，在工作流的 custom_data 配置中设置 unitsScale（例如 units: "uV" 时设为 1e-6）。

同一份数据——以及你的结果——可以渲染为助手可查看的 PNG 图像，而不只是 JSON：plots.dataset（PSD / 频带功率热图 / 头皮地形图 / 时频图）、plots.erp（各类别诱发电位蝴蝶图——训练前检查类别结构）、plots.confusion（运行后查看哪些类别实际被混淆）、plots.leaderboard（按数据集显示 CI 误差线柱，突出显示 BYO 提交）。设置 save=true 还会将 PNG 写入 NIMBUS_EXPORT_DIR/plots/。

plots.confusion(execution_id="exec_123")  # → image + per-class accuracy
plots.dataset(kind="psd", source="dataset", dataset="BNCI2014_001", subject="S01")
stats.grouped(execution_ids=["exec_123", "exec_124"])  # cluster-aware t-interval + p

上传数据

使用你自己的记录数据，替代或补充公开数据集。

“我有一份位于 ~/recordings/session-01.edf 的 .edf 记录文件——上传它，并围绕它构建工作流。”

Agent 会调用 data.upload(file_path=…)，将文件注册到后端并返回存储路径；随后将该路径放入 custom_data 节点的配置中（{"filePath": "<path>", "format": "edf", …}），供 pipeline.validate / execution.run / experiment.run 使用。对于不含嵌入元数据的纯 CSV/TSV/TXT，请传入 sampling_rate（Hz）——否则后端会默认使用 250 Hz；format 可覆盖基于扩展名的格式检测。

实验批次

一次 experiment.run 调用即可有节奏地运行 1-25 个工作流（最多同时执行 2 个训练任务），并汇总指标，而不必让 Agent 逐一轮询 25 次 execution.run。

“比较 CSP-LDA 和 EEGNet 在 BNCI2014_001 的受试者 1-3 上的表现。”

Agent 会构建六个训练图，调用 experiment.run(runs=[{name: "csp-lda-s1", train_graph: …}, …])，立即获取 experimentId，然后轮询 experiment.get(experiment_id)，直到状态变为 completed——先查看每个运行的状态，最后获取类似 {"kappa": {"mean": 0.61, "std": 0.08, "best": {name, value}}} 的 aggregates（仅对已完成的运行计算平均值/标准差/最佳值）。

使用项目

Agent 构建，人类检查。Agent 保存的流水线会写入真正的工作室项目，因此你可以打开画布，准确查看运行了什么。

“将此流水线保存为名为 ‘motor-imagery-baseline’ 的项目——我会在工作室中检查。”

project.create(name) 会创建容器，project.save(project_id, train_graph, expected_revision=…) 会写入图（布局会自动生成；传入 project.load 返回的 expected_revision，这样并发编辑会发生冲突，而不是静默覆盖），project.load(project_id) 会读取图，以便编辑或重新运行。 设置 MCP_LOCAL_USER_ID 为你的用户 ID 后，项目会显示在你的工作室项目列表中。

监控实时会话

流式会话运行期间，Agent 可以监控其遥测数据，并告诉你它观察到的情况。

“监控我的专注会话，并在信号质量下降时告诉我。”

Agent 会轮询 stream.telemetry(session_id)——获取最新预测、近期窗口、信号质量（meanChannelQuality、snrDb、artifactProbability）以及运行统计数据，并在质量下降时发出警告。每次轮询也会重置空闲监控计时器，因此，处于主动监控中的会话绝不会被自动停止；无人监控的会话会在 15 分钟后关闭。

校准受试者

引导式校准会将佩戴设备的人转化为自己的训练数据：通过提示引导的会话记录带标签的试次，然后 Agent 使用该录制内容训练受试者自己的分类器。

“在我的 BrainBit 上运行每类 10 次试次的 MI 校准，完成后训练我的个人分类器。”

五个工具组成的流程（均为非阻塞）：

# 1. Start (confirm-gated): fetches the paradigm's calibration template
#    (mi / p300 / sart / target_hit), patches in device + trial count, and
#    starts the session. The Studio app shows the cues on its calibration
#    dashboard automatically.
calibration.start(paradigm="mi", trials_per_class=10, confirm=true)
# → {started: true, executionId: "…"}

# 2. Poll: phase (baseline → imagery trials → complete), current trial, cue,
#    progress tally, and an ETA estimate from the timing SSOT.
calibration.status(execution_id="…")
# → {phase: "imagery", currentTrial: {index: 7, total: 20, class: "Left Hand",
#    cue: "← LEFT"}, progress: {trialsDone: 6, …}, estimatedRemainingSec: 105.0, …}

# 3./4. Pacing between trials (cues hold; resume anytime).
calibration.pause(execution_id="…")  # calibration.resume(...) to continue

# 5. When phase == "complete" the snapshot carries the recording:
#    calibration: {uploadId, path, filename, format}. Train from it.
calibration.train(execution_id="…")
# → {trainExecutionId: "…", calibrationUploadId: "…"} → poll execution.get,
#    then execution.results for the metrics (kappa, accuracy, …).

mi 使用默认的 mi_headband_csp_lda 模板（CAR → 8-30 Hz 带通 → CSP → LDA）训练；p300 使用 p300_hardware_xdawn_lda（对录制的闪光试次执行 xDAWN → LDA）训练；sart / target_hit 没有默认训练模板——请向 calibration.train 传入显式的 template_id（来自 catalog.templates）或你自己的 train_graph。无论采用哪种方式，第一个数据节点都会重接到录制上传内容上（custom_data 源固定到 uploadId），并保留模板的训练配置。

calibration.start 必须设置 confirm=true 才能运行——与 stream.start 一样，设备会戴到人的头上；请先调用 device.test。

需要 Pro 套餐——校准工作流和自定义数据训练受免费增值限制（免费套餐请求会被节点策略以 403 拒绝）。本地 X-MCP-Key 主体在桌面应用标记已登录的 Pro 会话时可通过（MCP_LOCAL_IS_PRO）；否则，它们也受节点策略限制。

校准→训练的交接在所有后端（包括桌面本地后端）上都会解析成功：使用当前版本录制的内容会在桌面存储中包含上传↔执行关联。较早版本录制的内容没有此关联——请重新运行 calibration.start（工具的状态提示也会说明这一点）。

安全

stream.start 必须设置 confirm=true 才能运行——它会连接 EEG 设备，并在人身上启动实时会话。X-MCP-Key 路径仅限机器本地使用（Fly 部署绝不接受此方式）；托管模式使用来自 nimbus-mcp login 的个人 Authorization: Bearer 令牌进行身份验证（见上文的身份验证）。通过 MCP 启动的会话在空闲 15 分钟后会自动停止（见上文的监控计时器说明）。