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