MGnify

MGnify MCP Server exposes MGnify resources and tools through the Model Context Protocol, enabling you to integrate MGnify data and actions into your MCP-enabled workflows and clients.

How to use

You connect to the MGnify MCP Server using an MCP client or integration tool. The server can run in stdio mode for direct IPC, or you can access it over HTTP if you enable the HTTP transport. In stdio mode, your client exchanges messages through standard input and output. In HTTP mode, your client talks to a locally exposed REST-like MCP endpoint.

Typical usage patterns include querying MGnify resources, invoking actions supported by the MCP server, and handling responses or errors within your application logic. Ensure your client is configured with the correct base URL (for HTTP) or uses the stdio channel (for local IPC). If you enable the HTTP transport, your client should connect to the exposed URL and use the MCP protocol over HTTP.

How to install

Prerequisites you need before installing the MGnify MCP Server:

• Python 3.10+ is recommended (the MCP SDK requires Python >= 3.10)
• pip >= 21
• Optional: Docker

Follow these concrete steps to set up locally:

# 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 example 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.

Additional configuration and notes

Environment variables you can configure to customize the server include the following. These are optional but commonly used when connecting to MGnify or controlling the server behavior.

MG_BASE_URL=https://www.ebi.ac.uk/metagenomics/api/v1
MG_API_KEY=YOUR_API_TOKEN
BIND=127.0.0.1
PORT=8173

Troubleshooting

If you run into issues, try these common checks to get back on track.

• Pip cannot find mcp or versions require Python 3.10+ — upgrade to Python 3.10 or newer.
• SSL or network errors to MGnify API — verify MG_BASE_URL and network connectivity. 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

If you are developing or testing locally, you can run unit tests and linters as part of your workflow. The project uses Pydantic v2 for input schemas and Requests for HTTP.

The entry point for the server is defined in the build configuration as mgnify-mcp, which maps to the Python module that starts the MCP server.

Security and environment considerations

Keep your MGnify API token secure. If you provide MG_API_KEY, it will be used for authenticated requests. Do not commit sensitive values into version control; prefer environment files or secret managers in production.