UniProt MCP Server

A Model Context Protocol (MCP) server that provides seamless access to UniProtKB protein data. Query protein entries, sequences, Gene Ontology annotations, and perform ID mappings through a typed, resilient interface designed for LLM agents.

✨ Features

🔌 Dual Transport: Stdio for local development and Streamable HTTP for remote deployments
📊 Rich Data Access: Fetch complete protein entries with sequences, features, GO annotations, cross-references, and taxonomy
🔍 Advanced Search: Full-text search with filtering by review status, organism, keywords, and more
🔄 ID Mapping: Convert between 200+ database identifier types with progress tracking
🛡️ Production Ready: Automatic retries with exponential backoff, CORS support, Prometheus metrics
📝 Typed Responses: Structured Pydantic models ensure data consistency
🎯 MCP Primitives: Resources, tools, and prompts designed for agent workflows

🚀 Quick Start

Installation

pip install uniprot-mcp

Run the Server

Local development (stdio):

uniprot-mcp

Remote deployment (HTTP):

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

The HTTP server provides:

MCP endpoint: http://localhost:8000/mcp
Health check: http://localhost:8000/healthz
Metrics: http://localhost:8000/metrics (Prometheus format)

Test with MCP Inspector

npx @modelcontextprotocol/inspector uniprot-mcp

📚 MCP Primitives

Resources

Access static or dynamic data through URI patterns:

| URI | Description | |-----|-------------| | uniprot://uniprotkb/{accession} | Raw UniProtKB entry JSON for any accession | | uniprot://help/search | Documentation for search query syntax |

Tools

Execute actions and retrieve typed data:

| Tool | Parameters | Returns | Description | |------|-----------|---------|-------------| | fetch_entry | accession, fields? | Entry | Fetch complete protein entry with all annotations | | get_sequence | accession | Sequence | Get protein sequence with length and metadata | | search_uniprot | query, size, reviewed_only, fields?, sort?, include_isoform | SearchHit[] | Full-text search with advanced filtering | | map_ids | from_db, to_db, ids | MappingResult | Convert identifiers between 200+ databases | | fetch_entry_flatfile | accession, version, format | string | Retrieve historical entry versions (txt/fasta) |

Progress tracking: map_ids reports progress (0.0 → 1.0) for long-running jobs.

Prompts

Pre-built templates for common workflows:

Summarize Protein: Generate a structured summary from a UniProt accession, including organism, function, GO terms, and notable features.

🔧 Configuration

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | UNIPROT_ENABLE_FIELDS | unset | Request minimal field subsets to reduce payload size | | UNIPROT_LOG_LEVEL | info | Logging level: debug, info, warning, error | | UNIPROT_LOG_FORMAT | plain | Log format: plain or json | | UNIPROT_MAX_CONCURRENCY | 8 | Max concurrent UniProt API requests | | MCP_HTTP_HOST | 0.0.0.0 | HTTP server bind address | | MCP_HTTP_PORT | 8000 | HTTP server port | | MCP_HTTP_LOG_LEVEL | info | Uvicorn log level | | MCP_HTTP_RELOAD | 0 | Enable auto-reload: 1 or true | | MCP_CORS_ALLOW_ORIGINS | * | CORS allowed origins (comma-separated) | | MCP_CORS_ALLOW_METHODS | GET,POST,DELETE | CORS allowed methods | | MCP_CORS_ALLOW_HEADERS | * | CORS allowed headers |

CLI Flags

# HTTP server flags
uniprot-mcp-http --host 127.0.0.1 --port 9000 --log-level debug --reload

📖 Usage Examples

Fetching a Protein Entry

# Using MCP client
result = await session.call_tool("fetch_entry", {
    "accession": "P12345"
})

# Returns structured Entry with:
# - primaryAccession, protein names, organism
# - sequence (length, mass, sequence string)
# - features (domains, modifications, variants)
# - GO annotations (biological process, molecular function, cellular component)
# - cross-references to other databases

Searching for Proteins

# Search reviewed human proteins
result = await session.call_tool("search_uniprot", {
    "query": "kinase AND organism_id:9606",
    "size": 50,
    "reviewed_only": True,
    "sort": "annotation_score"
})

# Returns list of SearchHit objects with accessions and scores

Mapping Identifiers

# Convert UniProt IDs to PDB structures
result = await session.call_tool("map_ids", {
    "from_db": "UniProtKB_AC-ID",
    "to_db": "PDB",
    "ids": ["P12345", "Q9Y6K9"]
})

# Returns MappingResult with successful and failed mappings

🛠️ Development

Prerequisites

Python 3.11 or 3.12
uv (recommended) or pip

Setup

# Clone the repository
git clone https://github.com/josefdc/Uniprot-MCP.git
cd Uniprot-MCP

# Install dependencies
uv sync --group dev

# Install development tools
uv tool install ruff
uv tool install mypy

Running Tests

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

# Run specific test file
uv run pytest tests/unit/test_parsers.py -v

# Run integration tests only
uv run pytest tests/integration/ -v

Code Quality

# Lint
uv tool run ruff check .

# Format
uv tool run ruff format .

# Type check
uv tool run mypy src

# Run all checks
uv tool run ruff check . && \
uv tool run ruff format --check . && \
uv tool run mypy src && \
uv run pytest

Local Development Server

# Stdio server
uv run uniprot-mcp

# HTTP server with auto-reload
uv run python -m uvicorn uniprot_mcp.http_app:app --reload --host 127.0.0.1 --port 8000

🏗️ Architecture

src/uniprot_mcp/
├── adapters/           # UniProt REST API client and response parsers
│   ├── uniprot_client.py  # HTTP client with retry logic
│   └── parsers.py         # Transform UniProt JSON → Pydantic models
├── models/
│   └── domain.py       # Typed data models (Entry, Sequence, etc.)
├── server.py           # MCP stdio server (FastMCP)
├── http_app.py         # MCP HTTP server (Starlette + CORS)
├── prompts.py          # MCP prompt templates
└── obs.py              # Observability (logging, metrics)

tests/
├── unit/               # Unit tests for parsers, models, tools
├── integration/        # End-to-end tests with VCR fixtures
└── fixtures/           # Test data (UniProt JSON responses)

📦 Publishing

This server is published to:

PyPI: uniprot-mcp
MCP Registry: io.github.josefdc/uniprot-mcp

Building and Publishing

# Build distribution packages
uv build

# Publish to PyPI (requires token)
uv publish --token pypi-YOUR_TOKEN

# Publish to MCP Registry (requires GitHub auth)
mcp-publisher login github
mcp-publisher publish

See docs/registry.md for detailed registry publishing instructions.

🤝 Contributing

Contributions are welcome! Please:

Read our Contributing Guidelines
Follow our Code of Conduct
Check the Security Policy for vulnerability reporting
Review the Changelog for recent changes

Quick start for contributors:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Make your changes with tests
Run quality checks: uv tool run ruff check . && uv tool run mypy src && uv run pytest
Commit using Conventional Commits (feat:, fix:, docs:, etc.)
Push and open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

UniProt Consortium: For providing comprehensive, high-quality protein data through their REST API
Anthropic: For the Model Context Protocol specification and Python SDK
Community: For feedback, bug reports, and contributions

🔗 Links

Documentation: GitHub Repository
UniProt API: REST API Documentation
MCP Specification: Model Context Protocol
Issues & Support: GitHub Issues

⚠️ Disclaimer

This is an independent project and is not officially affiliated with or endorsed by the UniProt Consortium. Please review UniProt's terms of use when using their data.

Built with ❤️ for the bioinformatics and AI communities

MCP Servers