mne-docs-mcp
v1.0.36
Published
MCP server providing access to MNE-Python documentation, source code, GitHub issues, and community forum
Maintainers
Readme
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 (
pythonon Windows,python3on 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 buildSet token:
# Linux/macOS
export MNE_GITHUB_TOKEN=ghp_your_token_here
# Windows PowerShell
$env:MNE_GITHUB_TOKEN="ghp_your_token_here"Start server:
npm startDefault 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:latestOr 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 -dThe compose file only requires MNE_GITHUB_TOKEN. Other settings use image defaults.
Tool List
list_mne_versionsget_mne_fileget_mne_docfind_mne_symbolsearch_mne_docssearch_mne_issuesget_mne_issueget_mne_issue_commentssearch_mne_forumget_mne_forum_topicget_symbol_referencesget_related_symbolsget_mne_changelogget_mne_examplelookup_mne_error
Package Support
Supported packages:
mne-python(default)mne-bids-pipelinemne-bidsmne-connectivitymne-nirsmne-rsamne-icalabelmne-realtimemne-lslmne-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.mjsAgainst another endpoint:
MNE_MCP_BASE=https://your-server.com/mcp node scripts/run-tests.mjsAdd timeout guard:
MNE_TOOL_TIMEOUT_MS=20000 node scripts/run-tests.mjsStable benchmark mode (for slow/stuck investigation):
node scripts/run-tests.mjs --benchmark-stable --warm-pass --stable-runs 3Development
npm run dev
npm run typecheck
npm run lint
npm test
npm run buildRelease
npm run release:patch # or :minor / :majorThe 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: verifyMNE_GITHUB_TOKEN- slow code-search tools: use benchmark mode and check
/metrics - parser failures: verify Python path (
MNE_PYTHON_PATH) - endpoint check:
/healthshould returnstatus=healthy
License
MIT
