Skip to main content
Glama

Add to Cursor Add to VS Code Add to Claude Add to ChatGPT Add to Codex Add to Gemini

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

Related MCP server: mcp-uniprot

šŸš€ 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

āš ļø 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

Available Tools

5 tools
fetch_entryC

Return a structured UniProt entry.

ParametersJSON Schema
NameRequiredDescriptionDefault
accessionYes
fieldsNo
versionNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
accessionYesPrimary accession identifier.
idNoUniProt entry name/ID.
reviewedYesTrue for Swiss-Prot, False for TrEMBL.
protein_nameNoRecommended protein name where available.
gene_symbolsNoCanonical gene symbols associated with the entry.
organismNoScientific name of the source organism.
taxonomy_idNoNCBI taxonomy identifier for the organism.
sequenceNoProtein sequence metadata when available.
featuresNoAnnotated sequence features.
goNoGene Ontology annotations extracted from the entry.
xrefsNoCross-references to external databases.
raw_payloadNoOriginal UniProt payload for debugging or future enrichment.

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description is the sole source of behavioral info. It only says 'structured' without explaining behavior like auth, errors, or idempotency. Output schema exists but is not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one sentence, concise, but so minimal that it sacrifices informativeness. It could be expanded while staying concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 3 parameters, no annotations, and existing output schema, the description fails to provide sufficient context for correct usage. It omits parameter roles, output format, and use cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It adds no explanation for parameters (accession, fields, version) beyond their names, leaving the agent uninformed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (return) and resource (structured UniProt entry). However, it does not differentiate from sibling tools like fetch_entry_flatfile, so it could be more specific.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. Sibling tools exist but are not mentioned, and no usage context is provided.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

fetch_entry_flatfileC

Return the UniProt flatfile (txt or fasta) for a specific entry version.

ParametersJSON Schema
NameRequiredDescriptionDefault
accessionYes
versionYes
formatNotxt

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description must fully disclose behavior. It only states it returns a flatfile, but omits potential rate limits, authentication, size limits, error handling, or whether the response is file content or a URL. This leaves significant uncertainty for the agent.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that conveys the core purpose. However, it could be considered slightly under-specified; still, it is well-structured and avoids unnecessary words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has 3 parameters, no annotations, and an output schema (which reduces need to describe return values), the description still lacks crucial context about parameter usage, default behaviors, and edge cases. It is insufficient for an agent to use it confidently without further inference.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description should explain parameters. It clarifies 'format' can be 'txt or fasta', but fails to define 'accession' and 'version' beyond being entry identifiers. No constraints or allowed values are given for these parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns a UniProt flatfile for a specific entry version, explicitly mentioning the available formats (txt or fasta). This distinguishes it from siblings like fetch_entry (likely returns structured data) and get_sequence (returns sequence only).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives such as fetch_entry, get_sequence, or search_uniprot. The agent is left to infer from the name and description alone.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_sequenceA

Return only the sequence metadata for an accession.

ParametersJSON Schema
NameRequiredDescriptionDefault
accessionYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It does not disclose behavioral traits such as read-only nature, required permissions, or what 'sequence metadata' includes. The output schema is present but not described.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no unnecessary words. It is highly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with an output schema, the description is adequate but minimal. It lacks usage guidance and behavioral context, but the output schema may cover return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description mentions 'for an accession', which maps to the single required parameter. However, with 0% schema description coverage, it adds only minimal clarity without examples, format, or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Return' and resource 'sequence metadata for an accession'. It clearly distinguishes itself from siblings like 'fetch_entry' which likely returns full entry data.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'only the sequence metadata' implies this tool is for cases where only metadata is needed, contrasting with other tools that return more. However, it does not explicitly name alternatives or state when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

map_idsC

Map identifiers between UniProt-supported namespaces.

ParametersJSON Schema
NameRequiredDescriptionDefault
from_dbYes
to_dbYes
idsYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
from_dbYesSource identifier namespace.
to_dbYesTarget identifier namespace.
resultsNoMapping from input IDs to resolved identifiers (empty list for no match).

TDQS

C2.7/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden. It only mentions 'map identifiers' without disclosing behavioral traits such as id limits, mapping directionality, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words. However, a slight expansion to clarify parameter roles would improve utility without harming conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Despite having an output schema, the description fails to cover parameter semantics and usage context. For a tool with three undocumented parameters, this is insufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema has 0% description coverage. The description implies that 'from_db' and 'to_db' are namespaces and 'ids' are identifiers, but it does not explain valid values or formats, leaving ambiguity.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states it maps identifiers between UniProt-supported namespaces, clearly indicating the verb and resource. It distinguishes from sibling tools that fetch entries or sequences. However, it lacks specificity about the mapping operation itself.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus alternatives. The description does not provide context on prerequisites, limitations, or scenarios for exclusion.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_uniprotC

Search UniProtKB and return curated hits.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryYes
sizeNo
reviewed_onlyNo
fieldsNo
sortNo
include_isoformNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Without annotations, the description should disclose behavioral traits. It only says 'search and return curated hits,' offering no details on pagination, rate limits, or mutation (if any). The tool's behavior remains opaque.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence, which is concise but lacks structure and fails to provide necessary details in a front-loaded manner. It is not overly verbose but under-informative.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given 6 parameters, no annotations, and an output schema exists but is not described, the description is incomplete. It does not explain what 'curated hits' entails or how parameters affect behavior.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 6 parameters with 0% description coverage, and the tool description adds no parameter information. The agent is left to infer meaning from parameter names alone, which is insufficient.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action (search) and resource (UniProtKB) and mentions 'curated hits' as output, which differentiates from sibling tools that retrieve specific entries or sequences. However, 'curated hits' is somewhat vague, preventing a perfect score.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus siblings like fetch_entry or get_sequence. There is no mention of prerequisites or alternatives, leaving the agent without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

TDQS

B3.2/5.0
Disambiguation4/5

Tools 1-3 all fetch data for a given entry but in different formats (structured, flatfile, sequence). They are distinct enough with clear descriptions, but an agent might briefly hesitate between fetch_entry and fetch_entry_flatfile. map_ids and search_uniprot are completely separate.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern with underscores (fetch_entry, fetch_entry_flatfile, get_sequence, map_ids, search_uniprot). No mixing of styles or abbreviations.

Tool Count5/5

5 tools is an appropriate number for a focused UniProt server. It covers the main operations (entry retrieval, sequence, ID mapping, search) without being too minimal or overwhelming.

Completeness4/5

The tool set covers core UniProt workflows: retrieving entries in multiple formats, extracting sequence, ID mapping, and search. Minor gaps like batch operations or advanced query filtering exist, but these are acceptable for a basic server.

Maintenance

ActivityInactive
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • A
    license
    B
    quality
    D
    maintenance
    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.
    5
    2
    MIT
  • A
    license
    Not graded
    quality
    C
    maintenance
    Provides access to UniProt protein sequence and function knowledge base, enabling search and retrieval of protein entries, proteomes, taxonomy, and feature annotations.
    7
    MIT
  • F
    license
    B
    quality
    D
    maintenance
    Provides programmatic access to AlphaFold protein structure predictions and UniProt data, enabling users to retrieve protein structures, summaries, and annotations through natural language.
    3
  • A
    license
    A
    quality
    A
    maintenance
    An MCP server that grounds protein research in the UniProt SPARQL endpoint, providing tools for querying proteins, sequences, variants, diseases, and more via intent-named tools and raw SPARQL.
    15
    MIT

Latest Blog Posts

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/fastmcp-me/uniprot-mcp'

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