# smaniches/uniprot-mcp [Health: Active] **Category:** Biology, Medicine and Bioinformatics **Repository:** https://github.com/smaniches/uniprot-mcp **GitHub Stars:** 3 **Views:** 3 **Installs:** 0 **Upvotes:** 0 **Directory Page:** https://allmcps.com/mcp/smaniches-uniprot-mcp ## Description Auditable UniProt MCP server: 41 tools over the UniProt knowledgebase (entries, features, variants, PTMs, GO terms, cross-references) with per-query SHA-256 provenance and offline replay. uvx uniprot-mcp-server ## Tools Capabilities this server exposes over MCP: - **uniprot_get_entry** — Fetch a UniProt protein entry by accession (e.g. P04637 for p53, P38398 for BRCA1). Returns function, gene, organism, disease associations, cross-references. - **uniprot_search** — The general-purpose entry point for finding UniProtKB proteins by any combination of gene, organism, keyword, or free text. Use this first when you don't already have an accession; use ``uniprot_get_entry`` once you do. Examples: '(gene:TP53) AND (organism_id:9606)', 'kinase AND reviewed:true'. ``reviewed_only`` and ``organism`` are convenience shortcuts equivalent to adding the corresponding clause to ``query`` yourself. - **uniprot_get_sequence** — Fetch the canonical protein sequence in FASTA format. Use this when you need the raw residue string itself (e.g. for local sequence analysis); for pre-computed chemistry derived from this same sequence (molecular weight, pI, hydrophobicity) call ``uniprot_compute_properties`` instead, which fetches the FASTA internally so you don't have to parse it yourself. Always returns markdown/plain-text FASTA — there is no ``response_format`` parameter because FASTA is already the interchange format. - **uniprot_get_features** — Return the full, unfiltered feature array for an entry: domains, binding sites, PTMs, signal peptides, and every other annotated region, optionally narrowed by ``feature_types``. For a residue-specific view ('what's at position 175?') use ``uniprot_features_at_position`` instead; for the curated subsets (active/binding sites, processing, PTMs alone) the dedicated ``uniprot_get_active_sites`` / ``uniprot_get_processing_features`` / ``uniprot_get_ptms`` tools apply the same filter server-side. - **uniprot_get_go_terms** — Get GO annotations grouped by aspect. - **uniprot_get_cross_refs** — List every external-database cross-reference UniProt has curated for an entry (PDB, Pfam, Ensembl, Reactome, KEGG, STRING, and dozens more), optionally narrowed to one ``database``. For the common single-database cases there are dedicated, richer tools that resolve structured details beyond a bare ID: ``uniprot_resolve_pdb`` (structures with method/resolution), ``uniprot_resolve_alphafold``, ``uniprot_resolve_interpro``, and ``uniprot_resolve_chembl``. Use this tool for any other database or to see the full cross-reference set at once. - **uniprot_get_variants** — List every literature-described natural variant UniProt has curated for an entry, including disease-associated mutations. Use this to see the full variant catalogue for a protein; to check one specific HGVS-shorthand change (e.g. 'R175H') use ``uniprot_lookup_variant`` instead, which does the position/residue matching for you. UniProt's natural-variant annotations only cover literature-described variants — for population-scale clinical significance data use ``uniprot_resolve_clinvar``. - **uniprot_id_mapping** — Map identifiers between UniProt and external databases (or between two external databases) via UniProt's ID mapping service. Submits an async job and polls it to completion server-side, so the call may take a few seconds for large batches. - **uniprot_batch_entries** — Fetch multiple entries in a single call. Use this instead of repeated ``uniprot_get_entry`` calls when you already have a list of accessions — one network round-trip instead of N, with invalid accessions reported rather than aborting the batch. - **uniprot_taxonomy_search** — Resolve an organism name to its NCBI taxonomy ID(s) — the numeric ID other UniProt tools expect (e.g. the ``organism`` parameter of ``uniprot_search``, or ``organism_id:`` in a query string). Returns each match's taxonomy ID, scientific name, common name, and rank (species / genus / etc.); a name can resolve to multiple IDs when it's ambiguous (e.g. a genus with several species), so inspect the rank and full scientific name before picking one. Use this before filtering any other search by organism if you only know the name, not the numeric ID. - **uniprot_get_keyword** — Fetch a UniProt keyword by ID (e.g. KW-0007 for Acetylation, KW-0539 for Nucleus). Returns name, definition, category, synonyms, GO cross-refs, and parent/child hierarchy. - **uniprot_search_keywords** — Search UniProt's controlled keyword vocabulary (the ``KW-####`` terms) by name or definition. Use this to discover a keyword ID from a concept; once you have the ``KW-####`` ID, call ``uniprot_get_keyword`` for its full record (definition, category, hierarchy, GO cross-references). Returns up to ``size`` matches, or an empty list if nothing matches. Examples: 'acetylation', 'nucleus', 'kinase activity'. - **uniprot_get_subcellular_location** — Fetch a UniProt subcellular-location term by ID (e.g. SL-0039 Cell membrane, SL-0086 Cytoplasm, SL-0191 Nucleus). Returns name, definition, category, GO cross-refs, and the is-a / part-of hierarchy. - **uniprot_search_subcellular_locations** — Search UniProt's controlled subcellular-location vocabulary (the ``SL-####`` terms) by name or definition. Use this to discover a location ID from a concept; once you have the ``SL-####`` ID, call ``uniprot_get_subcellular_location`` for its full record (definition, category, hierarchy, GO cross-references). Returns up to ``size`` matches, or an empty list if nothing matches. Examples: 'membrane', 'mitochondrion', 'cytoplasm'. - **uniprot_get_uniref** — Fetch a UniRef cluster by ID. Examples: UniRef100_P04637 (100 % identity, only exact-match members), UniRef90_P04637 (90 % identity), UniRef50_P04637 (50 %, broadest grouping). Returns representative member, member list, common taxon, last-updated date. - **uniprot_search_uniref** — Search for UniRef clusters by content (not by a known cluster ID — for that, use ``uniprot_get_uniref`` directly). Example: query='kinase' identity_tier='90' returns the 90% clusters matching 'kinase'. Use a looser tier (50) to find broad homology groups, a tighter tier (100) to find near-identical sequence sets. - **uniprot_resolve_orthology** — Group every orthology cross-reference in a UniProt entry by source database (KEGG / OMA / OrthoDB / eggNOG / HOGENOM / PhylomeDB / InParanoid / TreeFam / GeneTree / PAN-GO / PANTHER / OrthoInspector). Different databases use different inference methods; surfacing them side-by-side lets the agent reason about consensus when comparing orthologs across species. Pure-Python — no extra HTTP call beyond the entry fetch. - **uniprot_target_dossier** — One-call comprehensive characterisation of a UniProt entry, structured for drug-discovery / clinical workflows. Composes nine views over the same entry plus one FASTA fetch (so two upstream network calls, not nine): Identity · Function · Sequence chemistry · Structural evidence (PDB count + best-resolution + AlphaFold model id + InterPro count) · Drug-target context (ChEMBL ids, DrugBank count) · Disease associations (with MIM IDs) · Variants count · Functional annotations (top GO MF, subcellular, ECO diversity) · Cross-references summary For per-residue pLDDT confidence call ``uniprot_get_alphafold_confidence`` separately. For full disease detail call ``uniprot_get_disease_associations``. The dossier is the entry- level summary that decides which deeper tools are worth calling. - **uniprot_replay_from_cache** — Read a previously-cached UniProt response without hitting the upstream. The local provenance cache is opt-in via the ``UNIPROT_MCP_CACHE_DIR`` environment variable; when unset, this tool always reports cache-disabled. Useful for: reproducing a year-old answer from a sealed cache snapshot; working offline / behind air-gaps; reducing UniProt's load when running benchmarks twice. Returns the cached body text wrapped in the recorded Provenance. The annotation ``openWorldHint=False`` reflects that this tool consults the local file system only — no upstream call. - **uniprot_resolve_clinvar** — Look up ClinVar records for the gene encoded by a UniProt entry. First fetches the entry to extract the canonical gene symbol, then queries NCBI eutils ClinVar by gene (and optional protein-change filter, e.g. ``R175H``). Returns clinical-significance classification, review status, condition list (trait_set), molecular consequence, and the protein-change list per record. Critical for clinical workflows — UniProt's natural-variant annotations stop at literature-described variants. ClinVar carries every variant submitted by clinical labs, with curated significance classifications. Combine ``uniprot_lookup_variant`` (UniProt side) with ``uniprot_resolve_clinvar`` (population side) for a full variant-effect picture. Calls https://eutils.ncbi.nlm.nih.gov — declared in PRIVACY.md. - **uniprot_get_alphafold_confidence** — Fetch the per-residue confidence (pLDDT) summary for an entry's AlphaFold model, not just its existence. Returns the global mean pLDDT score plus the four-band distribution (very high ≥ 90 / confident 70-90 / low 50-70 / very low < 50) so the agent can decide whether to trust the model: 95% 'very high' is publication-grade, 40% 'very low' is largely disordered and structural inference is unsafe. Call ``uniprot_resolve_alphafold`` first if you only need the model ID and viewer link, not its confidence. This tool calls https://alphafold.ebi.ac.uk — declared in PRIVACY.md as a third party. Provenance carries source = AlphaFoldDB. - **uniprot_get_publications** — List the publications UniProt cites on an entry, with PubMed IDs, DOIs, titles, authors, journal, year, and the 'reference position' annotation (the experimental work each citation supports — e.g. 'CRYSTALLIZATION', 'PHOSPHORYLATION AT SER-15', 'INVOLVEMENT IN LI-FRAUMENI SYNDROME'). Pure composition over the entry's ``references`` block — no extra HTTP call beyond the entry fetch. - **uniprot_compute_properties** — Derived sequence chemistry for a UniProt entry: molecular weight, theoretical pI, GRAVY hydrophobicity, aromaticity, net charge at pH 7, extinction coefficient at 280 nm, amino-acid composition. Computed from the canonical FASTA via standard methods (Lehninger pK values, Kyte-Doolittle hydropathy, Pace 1995 ε₂₈₀ formula). Pure-Python — no additional external API call beyond the FASTA fetch. - **uniprot_features_at_position** — List every UniProt feature that overlaps a residue position (1-indexed). Answers the question 'what's at residue 175 of TP53?' by intersecting the entry's features with the given position. Useful for variant-effect interpretation — surfaces every domain, binding site, modification, mutagenesis annotation, and natural variant at a single residue in one call. - **uniprot_get_active_sites** — Return the active sites, binding sites, metal-binding residues, and DNA-binding regions annotated on a UniProt entry. Filtered view over the entry's feature array — this is the residue-level chemistry of the protein, the input to enzyme drug-design and antibiotic target-validation workflows. - **uniprot_get_processing_features** — Return the maturation and processing features (signal peptide, propeptide, transit peptide, initiator methionine, chain, peptide). These describe how the translated polypeptide is cleaved and targeted into its mature form — essential for therapeutic-protein engineering and pathogen-secretion-system analysis. A pre-filtered view over ``uniprot_get_features``; for post-translational chemical modifications instead of cleavage/targeting, use ``uniprot_get_ptms``. - **uniprot_get_ptms** — Return the post-translational modification features (modified residues, glycosylation sites, lipidation sites, disulfide bonds, cross-links). PTMs are functionally critical: they switch enzymes on, target proteins for degradation, anchor them to membranes, and fold them via disulfides. A pre-filtered view over ``uniprot_get_features``; for cleavage/targeting features instead of chemical modifications, use ``uniprot_get_processing_features``. The empty case carries an honest pointer to mass-spec databases (PhosphoSitePlus, GlyConnect) for additional evidence. - **uniprot_lookup_variant** — Look up an HGVS-shorthand amino-acid change (e.g. ``R175H``, ``V600E``, ``R248*``) in the UniProt entry's natural-variant annotations. Returns the matching variant feature(s) including the UniProt-curated description (often a disease association). A null result here does NOT mean a variant is benign — UniProt only annotates literature-described variants; ClinVar / dbSNP carry population-level data. - **uniprot_get_disease_associations** — Structured disease associations for a UniProt entry. Returns the diseases recorded in DISEASE-type comments with name, acronym, UniProt disease ID, OMIM cross-reference, description, and the annotation note. Critical for clinical interpretation — distinguishes a UniProt-curated disease association (literature-anchored) from a raw cross-reference. Empty result does not imply disease-irrelevant; see Open Targets / OMIM / DisGeNET for population-level evidence. - **uniprot_get_uniparc** — Fetch a UniParc sequence-archive record by its known UPI. Returns sequence, MD5/CRC64 checksums, cross-reference counts, linked UniProtKB accessions, and the common-taxa list. UniParc is the non-redundant sequence archive — every protein sequence ever submitted to a major public database has exactly one UniParc record, making this the tool to use when a UniProtKB accession doesn't exist for a sequence you have. Don't have a UPI yet? Use ``uniprot_search_uniparc`` to find one first. - **uniprot_search_uniparc** — Search the UniParc non-redundant sequence archive by taxonomy, source database, or other UniParc query fields — the entry point when you don't already have a UPI. Examples: 'taxonomy_id:9606' for human sequences, 'database:Ensembl' for Ensembl-derived entries. Once you have a UPI from the results, use ``uniprot_get_uniparc`` for the full record. - **uniprot_get_proteome** — Fetch a UniProt proteome by UP ID (e.g. UP000005640 = human reference). Returns organism, taxonomy lineage, protein count, gene count, BUSCO completeness score, annotation score, and component breakdown (chromosomes / contigs). - **uniprot_search_proteomes** — Search UniProt proteomes (whole-organism protein sets) by organism or proteome field. Use this to find a proteome's ``UP#########`` ID; once you have it, call ``uniprot_get_proteome`` for the full record (protein / gene counts, BUSCO completeness, component breakdown). Returns up to ``size`` matches, or an empty list if nothing matches. Examples: 'organism_id:9606' for human, 'proteome_type:1' for reference proteomes only, 'taxonomy_name:bacteria' for all bacterial proteomes. - **uniprot_get_citation** — Fetch a UniProt citation record by ID (typically a PubMed ID, e.g. 9840937). Returns title, authors, journal, year, volume, pages, and cross-references. - **uniprot_search_citations** — Search the UniProt citations index (the literature UniProt references) by title, author, or year. Use this to find a citation's ID (typically a PubMed ID); once you have it, call ``uniprot_get_citation`` for the full record. For the publications attached to one specific protein entry, use ``uniprot_get_publications`` instead. Returns up to ``size`` matches, or an empty list if nothing matches. Examples: 'p53 AND author:Vogelstein', 'BRCA1 AND year:[2020 TO 2024]'. - **uniprot_resolve_pdb** — List every PDB structure cross-referenced from a UniProt entry, with method, resolution, and chain coverage. Faster than parsing the raw cross-references blob — returns a structured list typed for downstream analysis. - **uniprot_resolve_alphafold** — Resolve the AlphaFoldDB cross-reference for a UniProt entry — typically one canonical model per accession. Includes a direct EBI viewer link. - **uniprot_resolve_interpro** — List InterPro signatures (domain / family classifications) for a UniProt entry, with names extracted from the entry's cross-reference properties. - **uniprot_resolve_chembl** — Resolve ChEMBL drug-target cross-references for a UniProt entry. Returns the ChEMBL target IDs with EBI viewer links — empty if the protein has no documented bioactivity data in ChEMBL. - **uniprot_get_evidence_summary** — Summarise and grade the ECO (Evidence and Conclusion Ontology) codes attached to a UniProt entry's annotations. Counts how many features and comments cite each evidence code, then classifies every occurrence as experimental (wet-lab, ECO:0000269), manual (curator-reviewed inference), or automatic (un-reviewed pipeline call) and collapses that into a single 0-100 evidence-confidence score with a high / moderate / low / very-low band. A score near 100 means the entry is dominated by direct experimental evidence; a score near 10 means it is almost entirely computationally inferred. Critical for any downstream agent that must distinguish 'wet-lab confirmed' annotations from 'inferred by similarity'. JSON output adds an ``evidence_confidence`` block (score, band, per-class breakdown, weights) alongside the raw ``evidence_counts``. - **uniprot_provenance_verify** — Re-fetch a previously recorded UniProt URL and verify it still returns the same release identifier and the same canonical response body (SHA-256). Pass the values from a prior response's provenance footer (`url`, `release`, `response_sha256`, `accept_header`); empty optional fields skip the corresponding check. Returns a verification report with explicit pass / drift / unreachable verdicts per check. ``accept_header`` must match the Accept header used for the original request (default ``application/json``; use ``text/plain;format=fasta`` for FASTA-originated provenance). Replaying the wrong header causes a guaranteed hash mismatch because the upstream serves different content depending on content negotiation. This is the single tool that converts every prior uniprot-mcp response into an independently auditable artefact — a year from now, a third party can take the recorded provenance footer and confirm the upstream still serves the exact same bytes. ## Claude Desktop Quick Installation Install path detected from listing signals. Uses `uvx` (confidence: high): ```json "mcpServers": { "uniprot-mcp": { "command": "uvx", "args": ["uniprot-mcp-server"], "env": { "UNIPROT_MCP_CACHE_DIR": "" } } } ``` **Requires environment variables:** `UNIPROT_MCP_CACHE_DIR` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for). ## Documentation ## What smaniches/uniprot-mcp MCP server does The smaniches/uniprot-mcp MCP server gives an MCP client structured access to UniProtKB, UniRef, UniParc, controlled vocabularies, and selected linked scientific databases. Its catalog covers 41 tools for finding entries, retrieving records, examining sequences and annotations, resolving cross-references, and assembling evidence for protein, drug-target, and clinical workflows. Entry-oriented tools can search by gene, organism, keyword, or free text, then retrieve a record by accession. Other tools return FASTA sequences, computed sequence properties, Gene Ontology terms, subcellular locations, keywords, publications, domains, binding sites, active sites, processing features, and post-translational modifications. Variant workflows include complete natural-variant lists, residue-position lookups, disease associations, ClinVar resolution, and identifier mapping. The server also supports structural and comparative work. It can resolve PDB, AlphaFold, InterPro, ChEMBL, and orthology references; retrieve AlphaFold confidence summaries; search or fetch UniRef clusters; and retrieve UniParc sequence-archive records. A target-dossier tool combines several entry-level views into one response for initial drug-discovery or clinical review. ## How it works The server is launched as a local MCP process and makes requests to upstream services as needed. Most data comes from the UniProt REST API. ClinVar lookups use NCBI eutils, while AlphaFold confidence requests use AlphaFoldDB; these external calls are identified in the supplied documentation. Successful responses record the UniProt release, retrieval timestamp, resolved source URL, and a SHA-256 digest. The provenance verification tool can re-fetch a source and compare its release and canonicalized response hash, allowing a user to check whether the upstream record has changed. The hash is calculated from canonical JSON rather than raw response bytes, so key ordering does not affect verification. The optional cache is controlled by `UNIPROT_MCP_CACHE_DIR`. When configured, `uniprot_replay_from_cache` reads a previously stored response and its provenance without making an upstream request. With the variable unset, replay reports that caching is disabled. This supports repeatable offline analysis or work in an air-gapped environment when a cache snapshot is available. ## Setup and configuration Run the project directly with: ```bash uvx uniprot-mcp-server ``` It can also be installed into an existing Python environment: ```bash pip install uniprot-mcp-server ``` The project requires Python 3.11 or newer according to its repository metadata. Use the package name `uniprot-mcp-server`; the documentation warns that a different PyPI package named `uniprot-mcp` is unrelated. Set `UNIPROT_MCP_CACHE_DIR` only when local provenance caching and replay are needed. No API key or other credential is specified for the server itself. ## Tools and capabilities Representative capabilities include: - Search UniProt entries and fetch one or many accessions. - Retrieve canonical FASTA sequences and calculate molecular weight, pI, hydrophobicity, charge, extinction coefficient, and composition. - Inspect GO annotations, features, PTMs, processing regions, active sites, cross-references, publications, diseases, and variants. - Map identifiers across UniProt and external databases. - Resolve ClinVar, PDB, AlphaFold, InterPro, ChEMBL, and orthology information where supported. - Search controlled keyword, subcellular-location, UniRef, UniParc, and taxonomy records. - Build a target dossier, verify provenance, and replay cached responses. ## Limitations and notes A missing UniProt natural-variant result does not establish that a variant is benign; the supplied documentation distinguishes literature-curated UniProt annotations from population-scale clinical data in ClinVar. Likewise, an empty disease-association result does not prove that a protein lacks disease relevance. Some operations can take longer than a simple entry lookup. Identifier mapping submits an asynchronous job and polls it to completion, particularly for larger batches. The target dossier still depends on upstream data, despite combining several views into one call. Offline replay requires a previously populated cache and does not fetch current records. The server's evidence is release- and retrieval-dependent. Verification checks whether the referenced upstream representation and release still match; it does not replace scientific assessment of the underlying annotation. _Full upstream README: https://allmcps.com/mcp/smaniches-uniprot-mcp/readme_