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:

1. Read our Contributing Guidelines
2. Follow our Code of Conduct
3. Check the Security Policy for vulnerability reporting
4. Review the Changelog for recent changes

Quick start for contributors:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes with tests
4. Run quality checks: uv tool run ruff check . && uv tool run mypy src && uv run pytest
5. Commit using Conventional Commits (feat:, fix:, docs:, etc.)
6. 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