uniprot-mcp 0.1.0
Model Context Protocol server that surfaces UniProtKB data as MCP resources, tools, and prompts.
License: MIT
Requires Python: >=3.11
Keywords: mcp, uniprot, bioinformatics, llm, agent

# UniProt MCP Server

mcp-name: io.github.josefdc/uniprot-mcp

The UniProt MCP server exposes curated UniProtKB data as Model Context Protocol
(MCP) resources, tools, and prompts. It allows MCP-compatible agents to fetch
protein entries, sequences, Gene Ontology annotations, and identifier mappings
from the UniProt REST API through a consistent, typed interface.

## Features

- **Protocols**: Supports both stdio (development) and streamable HTTP (remote
  deployments with proper CORS headers).
- **Resources**: `uniprot://uniprotkb/{accession}` provides raw entry JSON;
  `uniprot://help/search` documents query syntax.
- **Tools**: Structured outputs for `fetch_entry`, `get_sequence`,
  `search_uniprot`, and `map_ids` (with progress notifications).
- **Prompts**: Built-in prompt for summarising a UniProt accession.
- **Retries & resilience**: Tenacity-based retries for 429/5xx responses,
  progress reporting for long-running mapping tasks, and defensive parsing of
  UniProt payloads.

## Installation

```bash
pip install uniprot-mcp
```

## Quickstart

### Stdio server (development / MCP Inspector)

```bash
uniprot-mcp
```

This launches the stdio transport (the same entry point MCP Inspector uses).

### Streamable HTTP server

```bash
uniprot-mcp-http --host 0.0.0.0 --port 8000
```

The server exposes a health check at `/healthz` and the MCP endpoint at `/mcp`.
Browser clients can read the `Mcp-Session-Id` response header because the
server is configured with permissive CORS defaults.
If `prometheus-client` is installed (included by default), metrics are served at `/metrics`.

## Available MCP primitives

### Resources

- `uniprot://uniprotkb/{accession}` – returns raw UniProtKB entry JSON.
- `uniprot://help/search` – simple usage guide for `search_uniprot`.

### Tools

| Tool | Description |
| --- | --- |
| `fetch_entry(accession, fields=None)` | Fetch a UniProtKB entry and return a typed payload (`Entry`). Versioned entries require `fetch_entry_flatfile`. |
| `get_sequence(accession)` | Fetch minimal sequence metadata (`Sequence`). |
| `search_uniprot(query, size=10, reviewed_only=False, fields=None, sort=None, include_isoform=False)` | Search UniProtKB and return a list of hits (`SearchHit`). |
| `map_ids(from_db, to_db, ids)` | Submit/poll UniProt ID mapping jobs with progress reporting (`MappingResult`). |
| `fetch_entry_flatfile(accession, version, format="txt")` | Return a historical flatfile (txt or fasta) for a UniProt entry version. |

### Prompts

- **Summarize Protein** – prompts an agent to summarise a UniProt accession,
  optionally including organism, GO annotations, and notable features.

## Environment variables and CLI flags

| Variable | Default | Description |
| --- | --- | --- |
| `UNIPROT_ENABLE_FIELDS` | unset | When set, the server requests minimal field subsets from UniProt (reduces payload size). |
| `MCP_HTTP_HOST` | `0.0.0.0` | Bind host for `uniprot-mcp-http` (can also use `--host`). |
| `MCP_HTTP_PORT` | `8000` | Bind port for `uniprot-mcp-http` (or `--port`). |
| `MCP_HTTP_LOG_LEVEL` | `info` | Log level for uvicorn (or `--log-level`). |
| `MCP_HTTP_RELOAD` | `0` | Enable auto-reload for `uniprot-mcp-http` when set to `1/true` (or pass `--reload`). |
| `UNIPROT_LOG_LEVEL` | `info` | Application log level (`debug`, `info`, `warning`, `error`). |
| `UNIPROT_LOG_FORMAT` | `plain` | Log output format (`plain` or `json`). |
| `UNIPROT_MAX_CONCURRENCY` | `8` | Maximum concurrent outbound UniProt requests. |
| `MCP_CORS_ALLOW_ORIGINS` | `*` | Override CORS origins (comma-separated) for HTTP transport. |
| `MCP_CORS_ALLOW_METHODS` | `GET,POST,DELETE` | Allowed methods for CORS preflight. |
| `MCP_CORS_ALLOW_HEADERS` | `*` | Allowed request headers for CORS. |

Every HTTP response includes `X-Request-Id`. Forward this header in client requests to correlate logs across transports.

## Development

The project is managed with [uv](https://docs.astral.sh/uv/).

```bash
# Install dependencies
uv sync --group dev

# Lint & format check
uv tool run ruff check .
uv tool run ruff format --check .

# Type check
uv tool run mypy src

# Run tests (with coverage)
uv run pytest --maxfail=1 --cov=uniprot_mcp --cov-report=term-missing

# Launch stdio server for local inspection
uv run uniprot-mcp

# Launch HTTP server with auto-reload
uv run python -m uvicorn uniprot_mcp.http_app:app --reload
```

## Publishing & MCP Registry

1. Build artifacts: `uv build`
2. Publish to PyPI: `uv publish --token $PYPI_TOKEN`
3. Prepare/validate `server.json` (see `docs/registry.md` for the schema link).
4. Use [`mcp-publisher`](https://github.com/modelcontextprotocol/registry) to
   publish the server metadata, optionally linking a remote HTTP deployment.

## Support & Compatibility

- Python 3.11 and 3.12 are tested in CI.
- External dependencies are pinned via `uv.lock`.
- Issues and feature requests: [GitHub Issues](https://github.com/josefdc/Uniprot-MCP/issues)

## License

Distributed under the MIT License. See `LICENSE` for details.