MNE Docs MCP Server

MCP server for MNE ecosystem docs, source code, issues, and forum content.

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

Against another endpoint:

MNE_MCP_BASE=https://your-server.com/mcp node scripts/run-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:

1. Bumps version (package.json)
2. Updates server.json
3. Stages package.json, package-lock.json, server.json
4. Commits (Release vX.Y.Z)
5. Tags (vX.Y.Z)
6. 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