mne-docs-mcp

MNE Docs MCP Server

⚠️ Deprecated — this project moved to Python

mne-docs-mcp is archived. It is superseded by mne-docs, a zero-dependency Python CLI.

pip install mne-docs

Why: an AI assistant with a shell and local files can grep and read MNE's source better than any tool schema can rank for it. The MCP server's 15 tools, symbol ranking, and caching turned out to be scaffolding around one good idea — put the user's version of MNE on disk and read it. That idea is now a single command, with no server, no Node runtime, and no GitHub token.

v1.0.50 is the final release. It exists to fix one real bug before the lights go out: every code and docs search in v1.0.10–v1.0.49 silently returned zero results, because the GitHub code-search query carried an unsupported ref: qualifier. If you are staying on this package, upgrade to v1.0.50. Otherwise, please move to mne-docs.

What You Get

• 15 read-only MCP tools for docs/code/issues/forum/error lookup
• HTTP transport (/mcp) and stdio transport
• Python AST-based symbol parsing (no extra Python packages required)
• Built-in caching and GitHub rate-limit aware behavior
• Multi-package support across the MNE ecosystem for most code/docs tools

Requirements

• Node.js >=20
• Python 3 (python on Windows, python3 on Linux/macOS)
• GitHub token (MNE_GITHUB_TOKEN) with access to public repositories

Quick Start (Local HTTP)

git clone https://github.com/weiyongxu/mne-docs-mcp.git
cd mne-docs-mcp
npm install
npm run build

Set token:

# Linux/macOS
export MNE_GITHUB_TOKEN=ghp_your_token_here

# Windows PowerShell
$env:MNE_GITHUB_TOKEN="ghp_your_token_here"

Start server:

npm start

Default endpoint: http://127.0.0.1:8000/mcp
Health check: http://127.0.0.1:8000/health
Metrics: http://127.0.0.1:8000/metrics

MCP Client Integration

Stdio Mode (Claude Desktop / Kiro / Claude Code)

Use dist/index.js and set MNE_TRANSPORT=stdio:

{
  "mcpServers": {
    "mne-docs": {
      "command": "node",
      "args": ["/path/to/mne-docs-mcp/dist/index.js"],
      "env": {
        "MNE_GITHUB_TOKEN": "ghp_your_token_here",
        "MNE_TRANSPORT": "stdio"
      }
    }
  }
}

Remote HTTP Mode

{
  "mcpServers": {
    "mne-docs": {
      "type": "http",
      "url": "https://your-server.com/mcp"
    }
  }
}

Docker

docker run -p 8000:8000 \
  -e MNE_GITHUB_TOKEN=ghp_your_token_here \
  ghcr.io/weiyongxu/mne-docs-mcp:latest

Or use the included docker-compose.yml:

# Linux/macOS
export MNE_GITHUB_TOKEN=ghp_your_token_here

# Windows PowerShell
$env:MNE_GITHUB_TOKEN="ghp_your_token_here"

docker compose pull
docker compose up -d

The compose file only requires MNE_GITHUB_TOKEN. Other settings use image defaults.

Tool List

• list_mne_versions
• get_mne_file
• get_mne_doc
• find_mne_symbol
• search_mne_docs
• search_mne_issues
• get_mne_issue
• get_mne_issue_comments
• search_mne_forum
• get_mne_forum_topic
• get_symbol_references
• get_related_symbols
• get_mne_changelog
• get_mne_example
• lookup_mne_error

Package Support

Supported packages:

• mne-python (default)
• mne-bids-pipeline
• mne-bids
• mne-connectivity
• mne-nirs
• mne-rsa
• mne-icalabel
• mne-realtime
• mne-lsl
• mne-gui-addons

package parameter is supported by code/docs/issues/changelog/example/symbol tools.
Forum tools (search_mne_forum, get_mne_forum_topic) and lookup_mne_error do not take a package parameter.

Configuration

Key environment variables:

Variable	Default	Notes
MNE_GITHUB_TOKEN	—	Required
MNE_TRANSPORT	http	http or stdio
MNE_HOST	127.0.0.1	Use 0.0.0.0 in containers
MNE_PORT	8000	HTTP mode port
MNE_ALLOWED_ORIGINS	*	CORS/Origin allowlist
MNE_DEFAULT_PACKAGE	mne-python	Default package
MNE_PYTHON_PATH	python (Win) / python3 (Unix)	Parser executable
MNE_LOG_LEVEL	info	debug, info, warn, error
MNE_LOG_JSON	false	Structured logs

See .env.example for a minimal local template.

Testing and Diagnostics

Full tool test run:

node scripts/run-tests.mjs

Curated 25-example smoke test:

node scripts/run-example-tests.mjs

Against another endpoint:

MNE_MCP_BASE=https://your-server.com/mcp node scripts/run-tests.mjs
MNE_MCP_BASE=https://your-server.com/mcp node scripts/run-example-tests.mjs

Add timeout guard:

MNE_TOOL_TIMEOUT_MS=20000 node scripts/run-tests.mjs

Stable benchmark mode (for slow/stuck investigation):

node scripts/run-tests.mjs --benchmark-stable --warm-pass --stable-runs 3

Development

npm run dev
npm run typecheck
npm run lint
npm test
npm run build

Release

npm run release:patch   # or :minor / :major

The release script:

• Bumps version (package.json)
• Updates server.json
• Stages package.json, package-lock.json, server.json
• Commits (Release vX.Y.Z)
• Tags (vX.Y.Z)
• Pushes commit and tag

Tag push triggers release.yml, which publishes:

• GHCR Docker image
• npm package
• MCP Registry entry
• GitHub Release

Troubleshooting

• 401 / Bad credentials: verify MNE_GITHUB_TOKEN
• slow code-search tools: use benchmark mode and check /metrics
• parser failures: verify Python path (MNE_PYTHON_PATH)
• endpoint check: /health should return status=healthy

License

MIT