uniprot-mcp 0.1.0

Model Context Protocol server that surfaces UniProtKB data as MCP resources, tools, and prompts.

UniProt MCP Server

mcp-name: io.github.josefdc/uniprot-mcp

The UniProt MCP server exposes curated UniProtKB data as Model Context Protocol (MCP) resources, tools, and prompts. It allows MCP-compatible agents to fetch protein entries, sequences, Gene Ontology annotations, and identifier mappings from the UniProt REST API through a consistent, typed interface.

Features

• Protocols: Supports both stdio (development) and streamable HTTP (remote deployments with proper CORS headers).
• Resources: uniprot://uniprotkb/{accession} provides raw entry JSON; uniprot://help/search documents query syntax.
• Tools: Structured outputs for fetch_entry, get_sequence, search_uniprot, and map_ids (with progress notifications).
• Prompts: Built-in prompt for summarising a UniProt accession.
• Retries & resilience: Tenacity-based retries for 429/5xx responses, progress reporting for long-running mapping tasks, and defensive parsing of UniProt payloads.

Installation

pip install uniprot-mcp

Quickstart

Stdio server (development / MCP Inspector)

uniprot-mcp

This launches the stdio transport (the same entry point MCP Inspector uses).

Streamable HTTP server

uniprot-mcp-http --host 0.0.0.0 --port 8000

The server exposes a health check at /healthz and the MCP endpoint at /mcp. Browser clients can read the Mcp-Session-Id response header because the server is configured with permissive CORS defaults. If prometheus-client is installed (included by default), metrics are served at /metrics.

Available MCP primitives

Resources

• uniprot://uniprotkb/{accession} – returns raw UniProtKB entry JSON.
• uniprot://help/search – simple usage guide for search_uniprot.

Tools

Tool	Description
fetch_entry(accession, fields=None)	Fetch a UniProtKB entry and return a typed payload (Entry). Versioned entries require fetch_entry_flatfile.
get_sequence(accession)	Fetch minimal sequence metadata (Sequence).
search_uniprot(query, size=10, reviewed_only=False, fields=None, sort=None, include_isoform=False)	Search UniProtKB and return a list of hits (SearchHit).
map_ids(from_db, to_db, ids)	Submit/poll UniProt ID mapping jobs with progress reporting (MappingResult).
fetch_entry_flatfile(accession, version, format="txt")	Return a historical flatfile (txt or fasta) for a UniProt entry version.

Prompts

• Summarize Protein – prompts an agent to summarise a UniProt accession, optionally including organism, GO annotations, and notable features.

Environment variables and CLI flags

Variable	Default	Description
UNIPROT_ENABLE_FIELDS	unset	When set, the server requests minimal field subsets from UniProt (reduces payload size).
MCP_HTTP_HOST	0.0.0.0	Bind host for uniprot-mcp-http (can also use --host).
MCP_HTTP_PORT	8000	Bind port for uniprot-mcp-http (or --port).
MCP_HTTP_LOG_LEVEL	info	Log level for uvicorn (or --log-level).
MCP_HTTP_RELOAD	0	Enable auto-reload for uniprot-mcp-http when set to 1/true (or pass --reload).
UNIPROT_LOG_LEVEL	info	Application log level (debug, info, warning, error).
UNIPROT_LOG_FORMAT	plain	Log output format (plain or json).
UNIPROT_MAX_CONCURRENCY	8	Maximum concurrent outbound UniProt requests.
MCP_CORS_ALLOW_ORIGINS	*	Override CORS origins (comma-separated) for HTTP transport.
MCP_CORS_ALLOW_METHODS	GET,POST,DELETE	Allowed methods for CORS preflight.
MCP_CORS_ALLOW_HEADERS	*	Allowed request headers for CORS.

Every HTTP response includes X-Request-Id. Forward this header in client requests to correlate logs across transports.

Development

The project is managed with uv.

# Install dependencies
uv sync --group dev

# Lint & format check
uv tool run ruff check .
uv tool run ruff format --check .

# Type check
uv tool run mypy src

# Run tests (with coverage)
uv run pytest --maxfail=1 --cov=uniprot_mcp --cov-report=term-missing

# Launch stdio server for local inspection
uv run uniprot-mcp

# Launch HTTP server with auto-reload
uv run python -m uvicorn uniprot_mcp.http_app:app --reload

Publishing & MCP Registry

1. Build artifacts: uv build
2. Publish to PyPI: uv publish --token $PYPI_TOKEN
3. Prepare/validate server.json (see docs/registry.md for the schema link).
4. Use mcp-publisher to publish the server metadata, optionally linking a remote HTTP deployment.

Support & Compatibility

• Python 3.11 and 3.12 are tested in CI.
• External dependencies are pinned via uv.lock.
• Issues and feature requests: GitHub Issues

License

Distributed under the MIT License. See LICENSE for details.