uniprot-mcp
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@uniprot-mcpsearch for human insulin reviewed:true"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: mcp-uniprot
š Quick Start
Installation
pip install uniprot-mcpRun the Server
Local development (stdio):
uniprot-mcpRemote deployment (HTTP):
uniprot-mcp-http --host 0.0.0.0 --port 8000The HTTP server provides:
MCP endpoint:
http://localhost:8000/mcpHealth check:
http://localhost:8000/healthzMetrics:
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 |
| Raw UniProtKB entry JSON for any accession |
| Documentation for search query syntax |
Tools
Execute actions and retrieve typed data:
Tool | Parameters | Returns | Description |
|
|
| Fetch complete protein entry with all annotations |
|
|
| Get protein sequence with length and metadata |
|
|
| Full-text search with advanced filtering |
|
|
| Convert identifiers between 200+ databases |
|
|
| 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 |
| unset | Request minimal field subsets to reduce payload size |
|
| Logging level: |
|
| Log format: |
|
| Max concurrent UniProt API requests |
|
| HTTP server bind address |
|
| HTTP server port |
|
| Uvicorn log level |
|
| Enable auto-reload: |
|
| CORS allowed origins (comma-separated) |
|
| CORS allowed methods |
|
| 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 databasesSearching 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 scoresMapping 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 mypyRunning 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/ -vCode 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 pytestLocal 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 publishSee 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 pytestCommit 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
Available Tools
5 toolsfetch_entryC
Return a structured UniProt entry.
| Name | Required | Description | Default |
|---|---|---|---|
| accession | Yes | ||
| fields | No | ||
| version | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| accession | Yes | Primary accession identifier. |
| id | No | UniProt entry name/ID. |
| reviewed | Yes | True for Swiss-Prot, False for TrEMBL. |
| protein_name | No | Recommended protein name where available. |
| gene_symbols | No | Canonical gene symbols associated with the entry. |
| organism | No | Scientific name of the source organism. |
| taxonomy_id | No | NCBI taxonomy identifier for the organism. |
| sequence | No | Protein sequence metadata when available. |
| features | No | Annotated sequence features. |
| go | No | Gene Ontology annotations extracted from the entry. |
| xrefs | No | Cross-references to external databases. |
| raw_payload | No | Original UniProt payload for debugging or future enrichment. |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| accession | Yes | ||
| version | Yes | ||
| format | No | txt |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| accession | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| from_db | Yes | ||
| to_db | Yes | ||
| ids | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| from_db | Yes | Source identifier namespace. |
| to_db | Yes | Target identifier namespace. |
| results | No | Mapping from input IDs to resolved identifiers (empty list for no match). |
TDQS
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.
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.
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.
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.
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.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| size | No | ||
| reviewed_only | No | ||
| fields | No | ||
| sort | No | ||
| include_isoform | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
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.
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.
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.
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.
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.
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
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.
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.
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.
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
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
Protein research over UniProtKB ā search by function, fetch curated records, map IDs, proteomes.
UniProt MCP ā protein sequence + function database.
Search and fetch Wikidata entities, execute SPARQL queries, and resolve external identifiers.
Query STRING interactions, enrichment, annotations, homology, and PPI networks.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides 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.52MIT
- AlicenseNot gradedqualityCmaintenanceProvides access to UniProt protein sequence and function knowledge base, enabling search and retrieval of protein entries, proteomes, taxonomy, and feature annotations.7MIT
- FlicenseBqualityDmaintenanceProvides programmatic access to AlphaFold protein structure predictions and UniProt data, enabling users to retrieve protein structures, summaries, and annotations through natural language.3
- AlicenseAqualityAmaintenanceAn 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.15MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
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