MGnify MCP Server
This repository implements an MCP server that exposes MGnify resources and tools over the Model Context Protocol.
Prerequisites
- Python 3.10+ recommended (the
mcpSDK requires Python >= 3.10). The project metadata uses a marker to skip installingmcpon older Python, but the server cannot run without it. - pip >= 21
- Optional: Docker
Quick start (Python 3.10+)
-
Create and activate a virtual environment
- macOS/Linux: python3 -m venv .venv source .venv/bin/activate
- Windows (PowerShell): py -3.10 -m venv .venv .venv\Scripts\Activate.ps1
-
Install the package (editable) and dependencies pip install -e .
-
Configure environment (optional)
- Copy .env.example to .env and adjust values as needed cp .env.example .env
- Available variables:
- MG_BASE_URL: Override the MGnify API base URL (default: https://www.ebi.ac.uk/metagenomics/api/v1)
- MG_API_KEY: If you have an API token, it will be sent as Bearer auth
- BIND, PORT: Only used if you enable the HTTP transport in server.py
-
Optional: Run a local smoke test (no MCP client needed) python scripts/smoke_test.py
- This will call the MGnify API via the included client to ensure things work locally.
-
Run the MCP server (stdio transport) mgnify-mcp
- The server will run over stdio until the client disconnects. Use an MCP-compatible client/tooling to connect.
Using with Claude Desktop (example)
- Add to your
claude_desktop_config.jsonor the UI where MCP servers are configured: { "mcpServers": { "mgnify": { "command": "/path/to/venv/bin/mgnify-mcp", "env": { "MG_BASE_URL": "https://www.ebi.ac.uk/metagenomics/api/v1" } } } } Replace the command with the absolute path to your venv script.
Alternative: Docker
- Build docker build -t mgnify-mcp .
- Run (stdio is not practical via docker). If you want HTTP transport, uncomment serve_http in mgnify_mcp/server.py and rebuild, then: docker run --rm -p 8173:8173 --env-file .env mgnify-mcp Then configure your client to connect to http://localhost:8173
Troubleshooting
- pip cannot find mcp / versions ignored require Python >=3.10 Upgrade to Python 3.10 or newer. The server relies on the mcp SDK.
- SSL or network errors to MGnify API Check MG_BASE_URL and your network. The public API should be reachable without an API key; some endpoints may rate-limit.
- Rate limiting The server surfaces 429 as an error with retry-after from MGnify. Back off and retry.
Development tips
- Run unit/lint tools you prefer. The code uses Pydantic v2 for input schemas and Requests for HTTP.
- Entry point is defined in pyproject.toml: mgnify-mcp -> mgnify_mcp.server:main