MNE Docs MCP Server

MCP server providing access to MNE-Python documentation, source code, GitHub issues, and community forum across the MNE ecosystem.

Quick Start

``bash


Clone and install

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

Set GitHub token (required)

export MNE_GITHUB_TOKEN=ghp_your_token_here

Start server

npm start
`

Server runs on http://localhost:8000. Verify with curl http://localhost:8000/health.

MCP Client Integration

$3

Add to your MCP config (claude_desktop_config.json, .kiro/settings/mcp.json, or ~/.claude/settings.json):

`json
{
"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"
}
}
}
}
`

> Windows: Add "MNE_PYTHON_PATH": "python" to env.

$3

If you're running the server on a VPS or remote host:

Claude Code CLI:
`bash
claude mcp add mne-docs --transport http https://your-server.com/mcp
`

Config file (.mcp.json or ~/.claude.json):
`json
{
"mcpServers": {
"mne-docs": {
"type": "http",
"url": "https://your-server.com/mcp"
}
}
}
`

$3

`bash
MNE_TRANSPORT=http npm start


Connect to http://localhost:8000/mcp


`

$3

`bash
docker run -p 8000:8000 -e MNE_GITHUB_TOKEN=ghp_your_token mne-docs-mcp
`

$3

`bash


Set your token

export MNE_GITHUB_TOKEN=ghp_your_token_here

Start

docker-compose up -d

View logs

docker-compose logs -f
`

Tools

| Tool | Description |
|------|-------------|
| list_mne_versions | List available MNE releases |
| get_mne_file | Fetch source code |
| get_mne_doc | Get symbol documentation |
| find_mne_symbol | Search for symbols |
| search_mne_docs | Unified code/docs search |
| search_mne_issues | Search GitHub issues |
| get_mne_issue | Get issue details |
| get_mne_issue_comments | Get issue comments |
| search_mne_forum | Search community forum |
| get_mne_forum_topic | Get full forum discussion |
| get_symbol_references | Get callees/callers |
| get_related_symbols | Find related functions |
| get_mne_changelog | Get version changes |
| get_mne_example | Get tutorial code |
| lookup_mne_error | Diagnose MNE errors |

All tools support a package parameter to query across the MNE ecosystem: mne-python (default), mne-bids-pipeline, mne-bids, mne-connectivity, mne-nirs, mne-rsa, mne-icalabel, mne-realtime, mne-lsl, mne-gui-addons.

Configuration

| Variable | Description | Default |
|----------|-------------|---------|
| MNE_GITHUB_TOKEN | GitHub PAT (required) | - |
| MNE_PORT | Server port | 8000 |
| MNE_TRANSPORT | http or stdio | http |
| MNE_PYTHON_PATH | Python executable | python3 |
| MNE_LOG_LEVEL | debug/info/warn/error | info |

See .env.example for all options including cache TTLs and timeouts.

Architecture

`
┌─────────────────────────────────────────────────────────┐
│ TypeScript Server (Node.js) │
│ ├─ MCP Tools (McpServer API, SDK v1.18+) │
│ ├─ GitHub Client (rate limiting, caching) │
│ └─ Python Parser Bridge ──┐ │
└────────────────────────────┼────────────────────────────┘
▼
┌─────────────────┐
│ Python Parser │
│ (AST, stdlib) │
└─────────────────┘
`

Built with the official MCP TypeScript SDK.

Development

`bash
npm run dev # Watch mode
npm run build # Compile TypeScript
npm test # Run tests
npm run lint # ESLint
`

Releasing

First-time setup (one-time only):
`bash
npm login
npm publish
`

Then for all future releases:
`bash
npm run release:patch # 1.0.0 → 1.0.1
npm run release:minor # 1.0.0 → 1.1.0
npm run release:major # 1.0.0 → 2.0.0
`

This bumps versions, commits, tags, and pushes. GitHub Actions then publishes to npm and MCP Registry automatically.

Troubleshooting

- Rate limits: Ensure MNE_GITHUB_TOKEN is set
- Parser fails: Check Python 3 is installed; Windows users set MNE_PYTHON_PATH=python
- Test setup: Run npx tsx examples/mcp-client.ts to verify

Security

- GitHub token needs only public_repo scope — never commit tokens to version control
- Python parser uses ast.parse() only (no code execution)
- For production: restrict outbound to api.github.com and mne.discourse.group`, don't expose to public internet

License

MIT