io.github.nimbusbci/nimbus-mcp

Tools

• account.whoami

  Who you are authenticated as: account email, plan (isPro / pioneer), this month's free-run quota, and — with a hosted token — the token name and days until it expires. Call this first when setup guidance appears or to check which credential a session uses.

  shallow
• bids.export_dataset

  Export a Nimbus dataset as a BIDS-layout zip saved to NIMBUS_EXPORT_DIR/bids/. Continuous sources (EDF/BDF uploads, stream recordings) export as BIDS-raw (EDF byte-passthrough; recordings converted HDF5→EDF with events.tsv). Epoched sources (MOABB packs, trial-table uploads) export as BIDS-derivatives (data passthrough + descriptive trial_index/label/session/run events — no fabricated onsets). The zip embeds nimbus_export_manifest.json with sha256s.

  shallow
• bids.export_execution

  Export an execution's results as a BIDS-derivative zip (metrics.json, per-subject participants.tsv, protocol.json, full pipeline_snapshot.json, predictions.tsv when stored, provenance/execution.json) saved to NIMBUS_EXPORT_DIR/bids/.

  shallow
• calibration.pause

  Pause a running calibration between trials (cues hold; resume anytime).

  shallow
• calibration.resume

  Resume a paused calibration session.

  shallow
• calibration.start

  Start a guided subject calibration session (NON-BLOCKING; confirm-gated — the device goes on a human's head). The Nimbus Studio app shows the cues on its calibration dashboard automatically; poll calibration.status. Requires a Pro plan (hosted token or Pro session): calibration nodes and custom-data training are gated by the freemium node policy; local X-MCP-Key principals pass only when the desktop app flags the signed-in Pro session (MCP_LOCAL_IS_PRO).

  shallow
• calibration.status

  Live snapshot of a calibration session (phase, current trial, progress, paused). Once complete, carries the recorded upload — call calibration.train to turn it into the subject's own classifier.

  shallow
• calibration.train

  Train the subject's own classifier from a COMPLETED calibration session (NON-BLOCKING). Fetches the recorded upload, wires it into a train pipeline as a custom_data source, and starts the run. Requires a Pro plan (custom_data training is freemium-gated). The calibrate→train handoff resolves on every backend, desktop-local included; only recordings made before the desktop execution-linkage build resolve no upload — rerun calibration.start for those.

  shallow
• catalog.datasets

  Curated public EEG datasets (MOABB packs) available to pipelines.

  shallow
• catalog.leaderboard

  Public benchmark leaderboard: pipeline rankings per dataset. Two tracks: the top-level ``within_session`` block (curated suite pipelines) and ``crossSubject`` (leave-one-subject-out — curated pipelines plus BYO ``python_model`` submissions; BYO rows carry ``kind: "byo"`` and an ``owner`` name). Within each dataset, ``rows`` sort desc by ``meanAccuracyPct`` (95% CI in ``ciLoPct``/``ciHiPct``). ``packFingerprint`` identifies the exact dataset pack behind the scores; ``updated`` marks each dataset's most recent run. The ``pretrained_few_trial`` efficiency track means: accuracy at a protocol-fixed 100-trials-per-subject budget — the frozen-backbone / few-parameter rows that matter when calibration data is scarce (``paramsTrained`` shown per row so cost is readable next to accuracy).

  shallow
• catalog.node_schema

  Full config JSON schema + input/output ports for one node type.

  shallow
• catalog.nodes

  List Nimbus pipeline node types (data, preprocessing, features, models...). Use catalog.node_schema(node_type) for one node's full config schema and ports.

  shallow
• catalog.template

  Full template incl. the 'train' execGraph needed by execution.run/pipeline.validate.

  shallow
• catalog.templates

  List built-in starter pipelines (MI/P300/SSVEP...). catalog.template(id) returns the graph.

  shallow
• data.delete_upload

  Delete an uploaded file from your account (disk + registry). Requires confirm=True. Pass the path returned by data.upload (file.path). Only your own uploads can be deleted; missing paths return not-found.

  shallow
• data.inspect_dataset

  Exploratory summary of a public EEG dataset (MOABB pack): channels, sampling rate, trial/class balance, per-channel µV stats, band powers and a PSD overview. Look at the data BEFORE building pipelines: class balance drives stratification choices (imbalanced classes skew accuracy), and flatlined channels mean a montage/reference problem worth fixing first. subject is REQUIRED (the backend 400s without it) — get the subject list via catalog.datasets, e.g. "S01"; a comma-list like "S01,S03" loads a cohort. mode: training | evaluation | all. Units note: values are ASSUMED volts by the loader — a µV-native file reads 1e6x too large; set unitsScale in a pipeline's custom_data config when needed.

  shallow
• data.inspect_file

  Exploratory summary of an EEG file (.edf/.bdf/.mat/.csv/.tsv/.txt/.h5): channels, sampling rate, trial/class balance, per-channel µV stats, band powers and a PSD overview. The path shape picks the source: ABSOLUTE path → read the file from disk (only on a LOCAL backend: desktop app / MCP local mode — no upload needed); RELATIVE path (the one data.upload returns) → describe the uploaded file, which works on ANY backend (hosted or local). Look at the data BEFORE building pipelines: class balance drives stratification choices, and flatlined channels mean a montage/reference problem worth fixing first. Units note: values are ASSUMED volts by the loader — a µV-native CSV reads 1e6x too large; set unitsScale in a pipeline's custom_data config when needed. On a hosted backend absolute paths are refused and this returns guidance (upload the file first or switch to a local backend).

  shallow
• data.upload

  Upload an EEG file (.edf/.bdf/.mat/.csv/.txt/.tsv/.h5/.hdf5, <=500MB) to the backend and get the registered path for a custom_data node. sampling_rate (Hz, e.g. 250.0) is REQUIRED for plain CSV/TSV/TXT files without embedded metadata — the backend silently assumes 250 Hz otherwise, which mis-times epochs, filters and spectral features. format overrides extension-based detection (auto, mat, csv, tsv, txt, edf, bdf, h5, hdf5).

  shallow
• device.list

  EEG devices supported by this backend (OpenBCI, Muse, BrainBit, LSL, PiEEG...).

  shallow
• device.test

  Test a device connection WITHOUT starting a stream (safe, no confirm needed).

  shallow
• execution.artifacts

  Trained artifacts (models/filters, e.g. *.pkl) saved by an execution.

  shallow
• execution.cancel

  Cancel a running execution.

  shallow
• execution.download_artifact

  Download one artifact file to NIMBUS_EXPORT_DIR/executions/<id>/ and return its path.

  shallow
• execution.get

  Execution status summary (status: running/completed/failed/cancelled).

  shallow
• execution.list

  Recent executions. Optional status filter (running/completed/failed/cancelled).

  shallow
• execution.results

  Metrics for a completed run. Trimmed by default (accuracy, kappa, ITR, confusion matrix, per-class); full=True returns the complete result object.

  shallow
• execution.run

  Start a pipeline run (NON-BLOCKING). Returns executionId — poll with execution.get() until status is completed/failed, then execution.results(). If an identical graph is already running for you, the run still starts but the response carries a ``warning`` + ``duplicateOf`` ids (cancel one with execution.cancel to avoid paying twice).

  shallow
• experiment.get

  Experiment snapshot: status (running/completed/failed), per-run rows ({name, executionId, status, error?, metrics?}) and, once finished, aggregates {metric: {mean, std, best: {name, value}}} over completed runs only (std = population; None below 2 values).

  shallow
• experiment.run

  Run 1-25 pipelines as ONE paced experiment (NON-BLOCKING). Returns an experimentId immediately; a background thread submits at most 2 runs at a time (min(max_concurrent, 2)), retries queue-full up to 3 times per run, and polls each execution to completion. Poll experiment.get() for per-run status and, once finished, aggregated metrics.

  shallow
• foundation.compare

  Run every available pretrained backbone on YOUR data and see which wins — a ranked bar chart with CI whiskers, params, and wall time per backbone. Backbones that can't process your data (window size, channel count) are noted, not silently skipped. Each backbone embeds your trials frozen (the exact foundation_features preprocessing), a LDA is cross-validated on the embeddings, and meta.results carries the per-backbone accuracy, CI, embed dim, params, and time — pick the foundation_features backbone by measurement, not vibes.

  shallow
• leaderboard.mine

  List your leaderboard submissions (newest first), all datasets.

  shallow
• leaderboard.status

  Fetch one of your leaderboard submissions (owner-only). Returns status (queued | scoring | done | failed), metrics when done (meanAccuracyPct + CI, same shape as leaderboard rows), or the error that failed it.

  shallow
• leaderboard.submit

  Submit a BYO python_model to a leaderboard track for server-side scoring. Nimbus scores it server-side under the track's fixed protocol — you submit code, never results. Poll ``leaderboard.status`` with the returned ``submissionId``; scoring takes minutes (classical) to tens of minutes (deep). Requirements must be plain PyPI names/specs (max 20, no URLs). Identical code resubmission is idempotent per track (``deduplicated: true``).

  shallow
• pipeline.export

  Export the pipeline as a standalone runnable Python bundle (zip saved locally).

  shallow
• pipeline.validate

  Validate a pipeline graph before running. ExecGraphSnapshot: {nodes: [{id, type, config}], connections: [{from, to}]}. Build it from catalog.template(id).train or from scratch using catalog.nodes().

  shallow
• pipeline.validate_node

  Validate one node's config (schema + semantic checks). Catches the same value errors as pipeline.validate for a single node (inverted bandpass, CSP components vs channel count when dataset is set).

  shallow
• plots.confusion

  Confusion-matrix figure for one execution: heatmap with trial counts + per-class accuracy bars, rendered as a PNG the assistant can see. Use it right after execution.results to eyeball WHICH classes are confused, not just the accuracy number.

  shallow
• plots.dataset

  Figure over an EEG data source — the visual companion to data.inspect_dataset. kind=psd (Welch, channel mean bold), kind=bandpower (channel × band dB heatmap), kind=topomap (band-power scalp map), kind=spectrogram (time-frequency for one channel). Sources are the same ones inspect uses: MOABB packs, uploads, local files.

  shallow
• plots.erp

  ERP butterfly figure from epoched data: one subplot per class, all channel means (thin) + across-channel mean (bold), time-locked to the trial event. Shows whether class-conditioned evoked structure exists BEFORE training anything.

  shallow
• plots.leaderboard

  Leaderboard bar chart for one dataset: accuracy with 95% CI whiskers, best first; BYO python_model submissions highlighted in a distinct color. The visual companion to catalog.leaderboard. On the pretrained_few_trial track the figure also includes the classical LOSO baseline as a muted side panel for comparison.

  shallow
• project.create

  Create a project (container for one pipeline document). Returns projectId.

  shallow
• project.delete

  Delete a project (and its saved pipeline document) from the studio workspace. Requires confirm=True: this removes the project from the user's project list. Executions already run from it are not affected. Find ids with project.list.

  shallow
• project.list

  List projects owned by the current principal (agent work included).

  shallow
• project.load

  Load a project's saved pipeline (train graph + meta) for editing/re-running.

  shallow
• project.save

  Save a pipeline graph into a project (visible on the studio canvas). Handles revision conflicts automatically (one retry).

  shallow
• protocol.export_stats

  Paired pre/post analysis for one assignment's recorded sessions: per-block aggregates (descriptive + CSV), paired t / Wilcoxon / dz (per-statistic minimums: paired t and Cohen's dz need ≥ 3 completed sessions, Wilcoxon needs ≥ 5), specificity notes, the adaptive-threshold trajectory, and a pre/post figure (base64 PNG — render or save it to look at the effect). An assignment with no recordings yet returns the empty payload with a note, never an error.

  shallow
• protocol.list

  Every saved protocol id at its latest version.

  shallow
• protocol.pause

  Pause a running protocol session (blocks freeze; the session and device stay alive — resume with protocol.resume). Simulated and playback sessions only while paused: no data is recorded.

  shallow
• protocol.resume

  Resume a paused protocol session (restarts the server-driven device loop). Live-hardware resume requires a Pro plan; simulated sessions are free. Pass the session's channel count (start_assignment reports it).

  shallow
• protocol.save

  Validate and persist the NEXT VERSION of a protocol document (confirm-gated: each call appends a version row; accidental calls clutter the version history). Edits create a new version — the assignment pins the version it runs.

  shallow
• protocol.session_status

  Live snapshot of a protocol deploy session: the scheduler block / session progress + threshold state (under ``protocol``) beside the telemetry window (recent indicators, quality, stats).

  shallow
• protocol.start_assignment

  Enroll a subject and prepare their neurofeedback deploy session (confirm-gated — a session runs on a human). Creates the assignment (yoked sham arms REQUIRE yoked_donor_upload_id: a recorded simulated session's upload — mint one by running an active-arm session and data.upload-ing its recording), then persists the protocol graph as a deployable execution. Requires a Pro plan for LIVE hardware sessions; simulated-source sessions (the default template) are free. Graph source: execution_id reuses THAT run's stored graph (it must contain a protocol_session node; no device is pre-connected — the deploy session's data source stays yours). Without execution_id the built-in template graph is cloned — simulated source → bandpass → bandpower_indicator → protocol_session stamped with the protocol refs — and a simulated device is connected to the returned session id. The session starts when a client opens {statusUrl} (the deploy WS), sends init_deployment with modelExecutionId={executionId}, then start; the Studio app shows the feedback panel automatically. Poll protocol.session_status; stop with protocol.stop (the recording's block annotations + assignment progression are written on stop).

  shallow
• protocol.stop

  Stop a protocol session (always safe to call): stops streaming, saves the block-annotated recording, advances the assignment when the scheduler reached its natural end, and disconnects the device (best-effort — a failed disconnect is reported, never raised).

  shallow
• protocol.validate

  Validate a neurofeedback protocol document WITHOUT saving it. Returns {valid: true, spec} on success, or {valid: false, errors: [...]} with the per-violation list (loc/msg) when the document is invalid — the verdict is data, never an exception.

  shallow
• python.validate

  Statically check a python_model script (BYO model class) without running it. Compiles the source and verifies the contract — a class with fit(X, y, info) and predict(X); optional predict_proba(X) unlocks confidence panels. Never executes the code, so it is safe against the hosted backend. Use it before execution.run to catch syntax errors, missing methods, or the wrong class name cheaply.

  shallow
• stats.grouped

  Cluster-aware group statistics across executions. REQUIREMENT (read first): each execution must have been run with an evaluation plan that STORED per-group (per-subject) accuracies for at least 3 groups — e.g. leave-one-subject-out (LOSO) or grouped CV over >= 3 subjects. A plain single-subject CV run (trials split within one subject, one group) stores no group stats and CANNOT be analysed here. If none of the given executions qualifies, the backend fails with ``nimbus.stats.insufficient_groups`` — that error means exactly this: re-run with a multi-subject / group-wise evaluation plan (>= 3 groups), or pass runs from such a sweep. What it does: pools the per-subject (per-group) accuracies each run's evaluation plan stored, then reports the between-group summary — mean accuracy with a t-interval and a one-sample t-test vs chance. Use this instead of eyeballing pooled accuracy: trials within a subject are not independent, so this is the MOABB-style number that survives review.

  shallow
• stream.start

  Connect an EEG device and START a live streaming session on the user's head. Requires confirm=True; call device.test first. Track with stream.status(). Idle watchdog: if no stream.status()/stream.telemetry() poll happens for idle_timeout_sec (default 900), the session is stopped and the device disconnected automatically — an abandoned stream never keeps running on the user's head. Any poll resets the timer; idle_timeout_sec=0 disables the watchdog.

  shallow
• stream.status

  Live snapshot of a streaming session (running, deviceConnected). Polling this also feeds the idle watchdog: each call resets the session's idle timer (see stream.start's idle_timeout_sec).

  shallow
• stream.stop

  Stop a streaming session and disconnect the device (always safe to call). Also removes the session from the idle watchdog so it cannot fire after an explicit stop.

  shallow
• stream.telemetry

  Live snapshot of a streaming session: latest prediction + recent window, signal quality (meanChannelQuality, snrDb, artifactProbability), indicators, running stats. Poll this while a session runs. Works with OR without a deployed model: modelless hardware streams (no classifier) report live signal quality + focus/relaxation band-power indicators with latestPrediction null; deployed sessions additionally carry predictions and confidence stats. Expect low confidence during filter/ASR warm-up (first seconds); quality < 0.5 or high artifactProbability means the signal is poor. 404 => session not active in this backend. Each poll also feeds the idle watchdog (see stream.start's idle_timeout_sec), keeping an actively watched session alive.

  shallow

Embed this server’s score

Tool count and median score across every tool in this server’s corpus — honest in a way a single cherry-picked tool’s badge wouldn’t be.

[![Vouch score](https://vouch.tools/api/servers/5a3ec8cd-1ac0-44ed-8044-0362b86d44bd/badge.svg)](https://vouch.tools/servers/5a3ec8cd-1ac0-44ed-8044-0362b86d44bd)