Skip to main content
Glama

UniProt MCP Server

by josefdc
GitHub
Python
MIT License
2
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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?

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Tools

Provides seamless access to UniProtKB protein database, enabling queries for protein entries, sequences, Gene Ontology annotations, full-text search, and ID mapping across 200+ database types.

  1. āœØ Features
    1. šŸš€ Quick Start
      1. Installation
      2. Run the Server
      3. Test with MCP Inspector
    2. šŸ“š MCP Primitives
      1. Resources
      2. Tools
      3. Prompts
    3. šŸ”§ Configuration
      1. Environment Variables
      2. CLI Flags
    4. šŸ“– Usage Examples
      1. Fetching a Protein Entry
      2. Searching for Proteins
      3. Mapping Identifiers
    5. šŸ› ļø Development
      1. Prerequisites
      2. Setup
      3. Running Tests
      4. Code Quality
      5. Local Development Server
    6. šŸ—ļø Architecture
      1. šŸ“¦ Publishing
        1. Building and Publishing
      2. šŸ¤ Contributing
        1. šŸ“„ License
          1. šŸ™ Acknowledgments
            1. šŸ”— Links
              1. āš ļø Disclaimer

                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