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

# 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

Claude Desktop / Kiro / Claude Code

Add to your MCP config (claude_desktop_config.json, .kiro/settings/mcp.json, or ~/.claude/settings.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.

Remote HTTP Server

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

Claude Code CLI:

claude mcp add mne-docs --transport http https://your-server.com/mcp

Config file (.mcp.json or ~/.claude.json):

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

Local HTTP Mode

MNE_TRANSPORT=http npm start
# Connect to http://localhost:8000/mcp

Docker

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

Docker Compose

# 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

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):

npm login
npm publish

Then for all future releases:

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