README.md•2.76 kB
# 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 `mcp` SDK requires Python >= 3.10). The project metadata uses a marker to skip installing `mcp` on older Python, but the server cannot run without it.
- pip >= 21
- Optional: Docker
Quick start (Python 3.10+)
1) 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
2) Install the package (editable) and dependencies
pip install -e .
3) 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
4) 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.
5) 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.json` or 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