Skip to main content
Glama

UniProt MCP Server

by josefdc
OverviewInspectNewSchemaRelated ServersScore
Python
Hybrid
MIT License
2

UniProt MCP Server

PyPI version Python versions License: MIT MCP Registry

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:

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

⚠️ 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

Deploy Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

Related Resources

Tools

New MCP Servers

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/josefdc/Uniprot-MCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server