uniprot-mcp-server

Search UniProtKB and return curated protein records. Pass text_search for a plain-language query (the 80% case) or query for the full Lucene field syntax (gene:TP53 AND organism_id:9606 AND reviewed:true) — exactly one is required. Reviewed (Swiss-Prot) entries are manually curated; unreviewed (TrEMBL) are computationally predicted and ~30x more numerous, so reviewed defaults to true to avoid drowning in predictions — set it false to include TrEMBL. Request facets (e.g. reviewed, model_organism) for server-side count breakdowns. Results page forward with an opaque cursor; UniProtKB has no offset paging. This is the discovery entry point — chain results[].accession into uniprot_get_entry for full records, or uniprot_get_sequence for FASTA.

{
  "type": "object",
  "properties": {
    "text_search": {
      "description": "Plain-language search across protein names, gene names, and function, e.g. \"kinase apoptosis\". Provide this OR query, not both.",
      "type": "string"
    },
    "query": {
      "description": "UniProtKB Lucene query with field prefixes — gene, organism_id, keyword (KW-xxxx), go (GO id), reviewed, protein_name, family, length, existence, accession. Example: \"gene:BRCA1 AND organism_id:9606 AND reviewed:true\". Provide this OR text_search, not both.",
      "type": "string"
    },
    "reviewed": {
      "default": true,
      "description": "Restrict to reviewed Swiss-Prot entries. Defaults to true (curated only); set false to include unreviewed TrEMBL. Ignored when query already pins a reviewed: clause.",
      "type": "boolean"
    },
    "organism_id": {
      "description": "Restrict to an NCBI taxon ID, e.g. 9606 for human. A convenience filter ANDed onto the query; resolve names with uniprot_get_taxonomy.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "fields": {
      "description": "Comma-separated UniProtKB field names to project, e.g. \"accession,gene_names,cc_function\". Omit for a sensible default set covering name, gene, organism, length, reviewed, score, and a function snippet.",
      "type": "string"
    },
    "facets": {
      "description": "Comma-separated upstream facet names for count breakdowns, e.g. \"reviewed,model_organism,proteins_with\". Returns a facets array alongside the hits.",
      "type": "string"
    },
    "size": {
      "description": "Number of hits per page (max 500). Omit for the server default.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 500
    },
    "cursor": {
      "description": "Opaque forward-pagination cursor from a prior response. Walk pages with this; random access to page N is not supported.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "accession": {
            "type": "string",
            "description": "UniProtKB primary accession, e.g. \"P04637\". The lookup key for uniprot_get_entry and uniprot_get_sequence."
          },
          "entryName": {
            "type": "string",
            "description": "UniProtKB mnemonic ID, e.g. \"P53_HUMAN\". Not an input key — use accession."
          },
          "proteinName": {
            "description": "Recommended full protein name. Omitted when the entry has none.",
            "type": "string"
          },
          "geneNames": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A gene name or synonym."
            },
            "description": "Gene names and synonyms for the protein."
          },
          "organism": {
            "type": "object",
            "properties": {
              "scientificName": {
                "type": "string",
                "description": "Organism scientific name, e.g. \"Homo sapiens\"."
              },
              "commonName": {
                "description": "Organism common name, e.g. \"Human\". Omitted when none.",
                "type": "string"
              },
              "taxonId": {
                "type": "number",
                "description": "NCBI taxonomy ID, e.g. 9606."
              }
            },
            "required": [
              "scientificName",
              "taxonId"
            ],
            "additionalProperties": false,
            "description": "Source organism."
          },
          "length": {
            "type": "number",
            "description": "Canonical sequence length in residues."
          },
          "reviewed": {
            "type": "boolean",
            "description": "True for reviewed Swiss-Prot (manually curated), false for unreviewed TrEMBL (computationally predicted)."
          },
          "annotationScore": {
            "type": "number",
            "description": "Annotation confidence on a 1–5 scale; higher means more curation evidence."
          },
          "proteinExistence": {
            "type": "string",
            "description": "Evidence level for the protein's existence, e.g. \"1: Evidence at protein level\"."
          },
          "functionSnippet": {
            "description": "First sentence(s) of the FUNCTION annotation, evidence references stripped. Omitted when no function is annotated.",
            "type": "string"
          }
        },
        "required": [
          "accession",
          "entryName",
          "geneNames",
          "organism",
          "length",
          "reviewed",
          "annotationScore",
          "proteinExistence"
        ],
        "additionalProperties": false,
        "description": "A UniProtKB search hit."
      },
      "description": "Matching protein hits for this page."
    },
    "facets": {
      "description": "Upstream facet count breakdowns. Present only when facets were requested.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Facet identifier, e.g. \"reviewed\"."
          },
          "label": {
            "type": "string",
            "description": "Human-readable facet label, e.g. \"Status\"."
          },
          "values": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string",
                  "description": "Facet value, e.g. \"true\"."
                },
                "label": {
                  "type": "string",
                  "description": "Human-readable value label, e.g. \"Reviewed (Swiss-Prot)\"."
                },
                "count": {
                  "type": "number",
                  "description": "Number of matches in this bucket."
                }
              },
              "required": [
                "value",
                "label",
                "count"
              ],
              "additionalProperties": false,
              "description": "A single facet bucket."
            },
            "description": "Count buckets for this facet."
          }
        },
        "required": [
          "name",
          "label",
          "values"
        ],
        "additionalProperties": false,
        "description": "A server-side facet breakdown."
      }
    },
    "totalResults": {
      "type": "number",
      "description": "Total matches for the query before pagination (from the upstream result count)."
    },
    "effectiveQuery": {
      "type": "string",
      "description": "The query as the server assembled and sent it to UniProtKB."
    },
    "cursor": {
      "description": "Forward cursor for the next page. Absent on the last page.",
      "type": "string"
    },
    "notice": {
      "description": "Guidance when nothing matched — echoes the query and suggests how to broaden.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `missing_query`: Neither text_search nor query was provided. `conflicting_query`: Both text_search and query were provided. Other values are possible when a failure originates below the handler.",
              "examples": [
                "missing_query",
                "conflicting_query"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "results",
        "totalResults",
        "effectiveQuery"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch full curated UniProtKB entries by accession in one batch (up to 20). Each entry carries function, catalytic activity, cofactors, subcellular location, disease involvement, PTMs, natural variants, isoforms, domains, GO terms, keywords, and cross-references. Partial failures do not abort the batch — resolved entries land in succeeded[] and unknown/withdrawn accessions in failed[]. Pass fields to trim the upstream projection. A single oversized record returns kind: "outline" (a section listing with byte sizes) instead of overflowing context — re-call the same accession with sections:[...] (e.g. ["disease","variants"]) to pull only those. This tool does not search: accessions come from uniprot_search_proteins.results[].accession or uniprot_map_ids. Strip any isoform suffix (P04637-2 to P04637) before calling.

{
  "type": "object",
  "properties": {
    "accessions": {
      "minItems": 1,
      "maxItems": 20,
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})$",
        "description": "A UniProtKB primary accession, e.g. \"P04637\". Canonical form only — strip any \"-N\" isoform suffix."
      },
      "description": "Accessions to fetch (1–20). From uniprot_search_proteins or uniprot_map_ids."
    },
    "fields": {
      "description": "Comma-separated UniProtKB field names to project, e.g. \"accession,gene_names,cc_function,ft_variant\". Omit for the full curated default set. Use this on the initial call to trim payload.",
      "type": "string"
    },
    "sections": {
      "description": "Only used to re-call after a kind: \"outline\" response — pass a subset of the outlined section keys to fetch just those sections. Do not pass on the initial call.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A section key from a prior outline response, e.g. \"disease\", \"variants\", \"function\", \"xrefs\"."
      }
    }
  },
  "required": [
    "accessions"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "kind": {
      "type": "string",
      "enum": [
        "full",
        "outline"
      ],
      "description": "Result kind. \"full\": the batch resolved — read succeeded[] and failed[]. \"outline\": a single record exceeded the context budget and is returned as a section listing — re-call the same accession with sections:[...] to pull specific sections."
    },
    "succeeded": {
      "description": "Entries that resolved successfully. Present when kind is \"full\".",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "accession": {
            "type": "string",
            "description": "UniProtKB primary accession."
          },
          "entryName": {
            "type": "string",
            "description": "UniProtKB mnemonic ID, e.g. \"P53_HUMAN\"."
          },
          "proteinName": {
            "description": "Recommended full protein name. Omitted when none.",
            "type": "string"
          },
          "genes": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A gene name or synonym."
            },
            "description": "Gene names and synonyms."
          },
          "organism": {
            "type": "object",
            "properties": {
              "scientificName": {
                "type": "string",
                "description": "Organism scientific name."
              },
              "commonName": {
                "description": "Organism common name. Omitted when none.",
                "type": "string"
              },
              "taxonId": {
                "type": "number",
                "description": "NCBI taxonomy ID."
              },
              "mnemonic": {
                "description": "Organism mnemonic, e.g. \"HUMAN\". Omitted when none.",
                "type": "string"
              }
            },
            "required": [
              "scientificName",
              "taxonId"
            ],
            "additionalProperties": false,
            "description": "Source organism."
          },
          "length": {
            "type": "number",
            "description": "Canonical sequence length in residues."
          },
          "reviewed": {
            "type": "boolean",
            "description": "True for reviewed Swiss-Prot, false for unreviewed TrEMBL."
          },
          "annotationScore": {
            "type": "number",
            "description": "Annotation confidence on a 1–5 scale."
          },
          "proteinExistence": {
            "type": "string",
            "description": "Protein-existence evidence level."
          },
          "function": {
            "description": "FUNCTION annotations. Absent on most TrEMBL entries.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "string",
                  "description": "The annotated text."
                },
                "evidence": {
                  "description": "Source evidence codes. Omitted when none are attached.",
                  "type": "array",
                  "items": {
                    "type": "string",
                    "description": "A PubMed/source evidence reference, e.g. \"PubMed:11025664\"."
                  }
                }
              },
              "required": [
                "value"
              ],
              "additionalProperties": false,
              "description": "An annotation with its source evidence preserved."
            }
          },
          "catalyticActivity": {
            "description": "Catalytic-activity reactions (Rhea-cross-referenced). Absent when not an enzyme.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Reaction equation, e.g. \"ATP + L-tyrosyl-[protein] = ...\"."
                },
                "ecNumber": {
                  "description": "Enzyme Commission number. Omitted when none.",
                  "type": "string"
                },
                "rheaId": {
                  "description": "Rhea reaction ID, e.g. \"RHEA:10596\". Omitted when none.",
                  "type": "string"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false,
              "description": "A catalyzed reaction."
            }
          },
          "cofactors": {
            "description": "Cofactors. Absent when none are annotated.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Cofactor name, e.g. \"Zn(2+)\"."
                },
                "chebiId": {
                  "description": "ChEBI identifier. Omitted when none.",
                  "type": "string"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false,
              "description": "A required cofactor."
            }
          },
          "subcellularLocation": {
            "description": "Subcellular locations. Absent when none are annotated.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "location": {
                  "type": "string",
                  "description": "Subcellular location, e.g. \"Nucleus\"."
                },
                "topology": {
                  "description": "Membrane topology. Omitted when not applicable.",
                  "type": "string"
                }
              },
              "required": [
                "location"
              ],
              "additionalProperties": false,
              "description": "A subcellular location."
            }
          },
          "disease": {
            "description": "Disease involvements (DISEASE comments). Absent when none.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "type": "string",
                  "description": "Disease name."
                },
                "diseaseId": {
                  "description": "UniProt disease accession, e.g. \"DI-01537\". Omitted when none.",
                  "type": "string"
                },
                "acronym": {
                  "description": "Disease acronym. Omitted when none.",
                  "type": "string"
                },
                "description": {
                  "description": "Disease description. Omitted when none.",
                  "type": "string"
                },
                "omimId": {
                  "description": "OMIM identifier. Omitted when none.",
                  "type": "string"
                }
              },
              "required": [
                "name"
              ],
              "additionalProperties": false,
              "description": "A disease association."
            }
          },
          "ptms": {
            "description": "Post-translational modification features (modified residues, glycosylation, etc.). Absent when none.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Feature type, e.g. \"Modified residue\" or \"Domain\"."
                },
                "description": {
                  "description": "Free-text description of the feature. Omitted when absent.",
                  "type": "string"
                },
                "location": {
                  "type": "object",
                  "properties": {
                    "start": {
                      "description": "Start residue position. Omitted when not exact.",
                      "type": "number"
                    },
                    "end": {
                      "description": "End residue position. Omitted when not exact.",
                      "type": "number"
                    }
                  },
                  "additionalProperties": false,
                  "description": "Residue range of the feature."
                },
                "featureId": {
                  "description": "Stable feature identifier, e.g. \"VAR_066493\". Omitted when none.",
                  "type": "string"
                }
              },
              "required": [
                "type",
                "location"
              ],
              "additionalProperties": false,
              "description": "A sequence feature."
            }
          },
          "variants": {
            "description": "Natural variants (dbSNP/ClinVar-linked). Absent when none.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "description": {
                  "description": "Variant description. Omitted when none.",
                  "type": "string"
                },
                "location": {
                  "type": "object",
                  "properties": {
                    "start": {
                      "description": "Start residue position. Omitted when not exact.",
                      "type": "number"
                    },
                    "end": {
                      "description": "End residue position. Omitted when not exact.",
                      "type": "number"
                    }
                  },
                  "additionalProperties": false,
                  "description": "Residue range of the variant."
                },
                "original": {
                  "description": "Original residue(s). Omitted when not a substitution.",
                  "type": "string"
                },
                "variation": {
                  "description": "Variant residue(s). Omitted when not a substitution.",
                  "type": "string"
                },
                "featureId": {
                  "description": "Variant identifier, e.g. \"VAR_066493\". Omitted when none.",
                  "type": "string"
                }
              },
              "required": [
                "location"
              ],
              "additionalProperties": false,
              "description": "A natural variant."
            }
          },
          "isoforms": {
            "description": "Isoforms (ALTERNATIVE PRODUCTS). Absent when only one product.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "isoformId": {
                  "type": "string",
                  "description": "Isoform accession, e.g. \"P04637-2\"."
                },
                "name": {
                  "description": "Isoform name. Omitted when none.",
                  "type": "string"
                },
                "sequenceStatus": {
                  "description": "Sequence status, e.g. \"Displayed\" or \"Described\". Omitted when none.",
                  "type": "string"
                }
              },
              "required": [
                "isoformId"
              ],
              "additionalProperties": false,
              "description": "An alternatively-spliced isoform."
            }
          },
          "domains": {
            "description": "Domain and region features. Absent when none.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "type": {
                  "type": "string",
                  "description": "Feature type, e.g. \"Modified residue\" or \"Domain\"."
                },
                "description": {
                  "description": "Free-text description of the feature. Omitted when absent.",
                  "type": "string"
                },
                "location": {
                  "type": "object",
                  "properties": {
                    "start": {
                      "description": "Start residue position. Omitted when not exact.",
                      "type": "number"
                    },
                    "end": {
                      "description": "End residue position. Omitted when not exact.",
                      "type": "number"
                    }
                  },
                  "additionalProperties": false,
                  "description": "Residue range of the feature."
                },
                "featureId": {
                  "description": "Stable feature identifier, e.g. \"VAR_066493\". Omitted when none.",
                  "type": "string"
                }
              },
              "required": [
                "type",
                "location"
              ],
              "additionalProperties": false,
              "description": "A sequence feature."
            }
          },
          "goTerms": {
            "description": "GO annotations. Absent when none.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "GO identifier, e.g. \"GO:0006915\"."
                },
                "term": {
                  "type": "string",
                  "description": "GO term label, e.g. \"apoptotic process\"."
                },
                "aspect": {
                  "type": "string",
                  "description": "GO aspect: P (process), F (function), or C (component)."
                }
              },
              "required": [
                "id",
                "term",
                "aspect"
              ],
              "additionalProperties": false,
              "description": "A Gene Ontology annotation."
            }
          },
          "keywords": {
            "description": "UniProt keywords. Absent when none.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string",
                  "description": "Keyword identifier, e.g. \"KW-0053\"."
                },
                "name": {
                  "type": "string",
                  "description": "Keyword name, e.g. \"Apoptosis\"."
                },
                "category": {
                  "description": "Keyword category. Omitted when none.",
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name"
              ],
              "additionalProperties": false,
              "description": "A UniProt keyword."
            }
          },
          "xrefs": {
            "description": "Cross-references grouped by database (PDB, Ensembl, RefSeq, ChEMBL, AlphaFoldDB). Chain a PDB id into protein-mcp-server, a ChEMBL id into chembl. Absent when none.",
            "type": "object",
            "propertyNames": {
              "type": "string"
            },
            "additionalProperties": {
              "type": "array",
              "items": {
                "type": "string",
                "description": "A cross-reference identifier in that database."
              }
            }
          }
        },
        "required": [
          "accession",
          "entryName",
          "genes",
          "organism",
          "length",
          "reviewed",
          "annotationScore",
          "proteinExistence"
        ],
        "additionalProperties": false,
        "description": "A full curated UniProtKB entry."
      }
    },
    "failed": {
      "description": "Accessions that were well-formed but not found in UniProtKB. Present when kind is \"full\".",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "accession": {
            "type": "string",
            "description": "The requested accession that did not resolve."
          },
          "error": {
            "type": "string",
            "description": "Why it failed and how to recover."
          }
        },
        "required": [
          "accession",
          "error"
        ],
        "additionalProperties": false,
        "description": "A per-accession failure."
      }
    },
    "sections": {
      "description": "Section outline returned when a single record exceeds the context budget. Present when kind is \"outline\".",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "description": "Section identifier — pass a subset in sections:[...] to retrieve it."
          },
          "bytes": {
            "type": "number",
            "description": "Serialized byte size of the section."
          }
        },
        "required": [
          "name",
          "bytes"
        ],
        "additionalProperties": false,
        "description": "An outlined section with its serialized size."
      }
    },
    "notice": {
      "description": "Re-call guidance when kind is \"outline\" — re-call the same accession with sections:[...] to pull specific sections.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `all_not_found`: Every accession in the batch was well-formed but unknown to UniProtKB. Other values are possible when a failure originates below the handler.",
              "examples": [
                "all_not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "kind"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Translate identifiers across databases via UniProt's ID-mapping service — gene names to accessions, accession to PDB / Ensembl / RefSeq / ChEMBL / GeneID, and back. The job runs asynchronously; this tool submits it and polls within a budget. A running job returns status "running" with a ticket; pass that ticket alone to poll the same job. A completed call returns status "finished" with one results page; when continuation is present, pass it alone to fetch the next completed page without re-submitting or polling the job. A gene name often maps to one reviewed Swiss-Prot accession plus dozens of unreviewed TrEMBL ones, so target UniProtKB-Swiss-Prot (reviewed only) for the usual intent, or UniProtKB / UniProtKB_AC-ID to include TrEMBL. Pair a gene-symbol from_db with tax_id to disambiguate species. Chain the resulting accessions into uniprot_get_entry.

{
  "type": "object",
  "properties": {
    "from_db": {
      "description": "Source database. Gene_Name = HGNC symbol (pair with tax_id); UniProtKB_AC-ID = accession or entry name; Ensembl/Ensembl_Protein = ENSG/ENSP; PDB; RefSeq_Nucleotide/RefSeq_Protein = NM_/NP_; ChEMBL; GeneID = NCBI Gene. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.",
      "type": "string",
      "enum": [
        "UniProtKB_AC-ID",
        "Gene_Name",
        "GeneID",
        "Ensembl",
        "Ensembl_Protein",
        "PDB",
        "RefSeq_Nucleotide",
        "RefSeq_Protein",
        "ChEMBL",
        "PomBase",
        "WormBase_Protein"
      ]
    },
    "to_db": {
      "description": "Target database. UniProtKB-Swiss-Prot = reviewed accessions only (the usual intent); UniProtKB / UniProtKB_AC-ID also include unreviewed TrEMBL. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.",
      "type": "string",
      "enum": [
        "UniProtKB",
        "UniProtKB-Swiss-Prot",
        "UniProtKB_AC-ID",
        "Gene_Name",
        "GeneID",
        "Ensembl",
        "Ensembl_Protein",
        "PDB",
        "RefSeq_Nucleotide",
        "RefSeq_Protein",
        "ChEMBL",
        "PomBase",
        "WormBase_Protein"
      ]
    },
    "ids": {
      "description": "Identifiers to translate. Required only when submitting a new mapping job; omitted when resuming with a ticket or continuation.",
      "maxItems": 100000,
      "type": "array",
      "items": {
        "type": "string",
        "description": "A source identifier in the from_db namespace, e.g. \"TP53\" for Gene_Name."
      }
    },
    "tax_id": {
      "description": "NCBI taxon ID to disambiguate ambiguous source IDs (e.g. a gene symbol across species). Recommended with Gene_Name; e.g. 9606 for human.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "ticket": {
      "description": "Running-job ticket from a prior status \"running\" response. Pass it alone to poll that job; do not combine it with continuation or submission inputs.",
      "type": "string",
      "minLength": 1
    },
    "continuation": {
      "description": "Completed-page continuation from a prior status \"finished\" response. Pass it alone to fetch the next page without polling or re-submitting.",
      "type": "object",
      "properties": {
        "jobId": {
          "type": "string",
          "minLength": 1,
          "description": "UniProt ID-mapping job identifier for the completed job."
        },
        "cursor": {
          "type": "string",
          "minLength": 1,
          "description": "Opaque cursor for the next completed results page."
        }
      },
      "required": [
        "jobId",
        "cursor"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "enum": [
        "finished",
        "running"
      ],
      "description": "Job state: \"finished\" (one completed results page included) or \"running\" (poll with ticket)."
    },
    "results": {
      "description": "Resolved mappings on this completed page (present only when status is \"finished\"). Failed source IDs are reported in unmappedIds.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "from": {
            "type": "string",
            "description": "The source identifier that was mapped."
          },
          "to": {
            "type": "string",
            "description": "The resolved target identifier (e.g. a UniProtKB accession)."
          }
        },
        "required": [
          "from",
          "to"
        ],
        "additionalProperties": false,
        "description": "A single from→to mapping."
      }
    },
    "ticket": {
      "description": "Running-job ticket (present only when status is \"running\"). Pass it alone to poll the same job.",
      "type": "string"
    },
    "continuation": {
      "description": "Next completed-page continuation (finished jobs only). Pass it alone to fetch the next page; absent on the terminal page.",
      "type": "object",
      "properties": {
        "jobId": {
          "type": "string",
          "minLength": 1,
          "description": "UniProt ID-mapping job identifier for the completed job."
        },
        "cursor": {
          "type": "string",
          "minLength": 1,
          "description": "Opaque cursor for the next completed results page."
        }
      },
      "required": [
        "jobId",
        "cursor"
      ],
      "additionalProperties": false
    },
    "mappedCount": {
      "description": "Number of resolved mappings (finished jobs only).",
      "type": "number"
    },
    "unmappedIds": {
      "description": "Source IDs UniProt reported as failed on this completed page. Absent when none failed.",
      "type": "array",
      "items": {
        "type": "string",
        "description": "A source ID that resolved to nothing."
      }
    },
    "notice": {
      "description": "Status guidance — e.g. that the job is still running, or that no IDs mapped.",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `missing_inputs`: No complete submission, running-job ticket, or completed-page continuation was provided. `conflicting_inputs`: Submission inputs, a running-job ticket, or a completed-page continuation were combined. `unsupported_db_pair`: The from_db/to_db combination is not supported by the ID-mapping service. `invalid_ticket`: The resume ticket is unknown or has expired server-side (UniProt holds jobs only temporarily). `invalid_continuation`: The completed-page continuation refers to a result page that is unknown or expired. Other values are possible when a failure originates below the handler.",
              "examples": [
                "missing_inputs",
                "conflicting_inputs",
                "unsupported_db_pair",
                "invalid_ticket",
                "invalid_continuation"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "status"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch the reference proteome for an organism by UPID (e.g. "UP000005640") or NCBI taxon ID (e.g. 9606) — provide exactly one. Returns metadata inline: proteome type, total protein count, BUSCO completeness (score, complete/fragmented/missing counts, lineage dataset), and the genome assembly accession. The protein set is opt-in via include_proteins (it is large — human is ~147,506) and returns a capped page with a forward cursor; narrow it with the query filter (UniProtKB Lucene syntax) for a subset. Resolve an organism name to a taxon ID first with uniprot_get_taxonomy.

{
  "type": "object",
  "properties": {
    "upid": {
      "description": "Proteome UPID. Provide this OR taxon_id, not both.",
      "anyOf": [
        {
          "type": "string",
          "const": ""
        },
        {
          "type": "string",
          "pattern": "^UP[0-9]{9}$",
          "description": "Proteome identifier, e.g. \"UP000005640\"."
        }
      ]
    },
    "taxon_id": {
      "description": "NCBI taxon ID, e.g. 9606 for human. Resolves to the reference proteome. Provide this OR upid, not both.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "include_proteins": {
      "default": false,
      "description": "When true, also return a capped, cursor-paginated page of the proteome's proteins. Defaults to false — metadata alone is the common case.",
      "type": "boolean"
    },
    "query": {
      "description": "Optional UniProtKB Lucene filter to narrow the protein list, e.g. \"reviewed:true AND keyword:KW-0067\". Only applies when include_proteins is true.",
      "type": "string"
    },
    "size": {
      "description": "Proteins per page when include_proteins is true (max 500). Omit for the server default.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 500
    },
    "cursor": {
      "description": "Forward-pagination cursor from a prior protein page. Only meaningful with include_proteins.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "proteome": {
      "type": "object",
      "properties": {
        "upid": {
          "type": "string",
          "description": "Proteome identifier, e.g. \"UP000005640\"."
        },
        "proteomeType": {
          "type": "string",
          "description": "Proteome type, e.g. \"Reference proteome\"."
        },
        "organism": {
          "type": "object",
          "properties": {
            "scientificName": {
              "type": "string",
              "description": "Organism scientific name."
            },
            "commonName": {
              "description": "Organism common name. Omitted when none.",
              "type": "string"
            },
            "taxonId": {
              "type": "number",
              "description": "NCBI taxonomy ID."
            },
            "mnemonic": {
              "description": "Organism mnemonic, e.g. \"HUMAN\". Omitted when none.",
              "type": "string"
            }
          },
          "required": [
            "scientificName",
            "taxonId"
          ],
          "additionalProperties": false,
          "description": "Source organism."
        },
        "proteinCount": {
          "type": "number",
          "description": "Total number of proteins in the proteome."
        },
        "busco": {
          "description": "BUSCO completeness report. Absent for proteomes without one.",
          "type": "object",
          "properties": {
            "complete": {
              "type": "number",
              "description": "Complete BUSCO genes."
            },
            "completeSingle": {
              "type": "number",
              "description": "Complete and single-copy BUSCOs."
            },
            "completeDuplicated": {
              "type": "number",
              "description": "Complete and duplicated BUSCOs."
            },
            "fragmented": {
              "type": "number",
              "description": "Fragmented BUSCOs."
            },
            "missing": {
              "type": "number",
              "description": "Missing BUSCOs."
            },
            "total": {
              "type": "number",
              "description": "Total BUSCO genes searched."
            },
            "lineageDb": {
              "description": "BUSCO lineage dataset, e.g. \"primates_odb10\". Omitted when none.",
              "type": "string"
            },
            "score": {
              "description": "Completeness percentage (0–100). Omitted when none.",
              "type": "number"
            }
          },
          "required": [
            "complete",
            "completeSingle",
            "completeDuplicated",
            "fragmented",
            "missing",
            "total"
          ],
          "additionalProperties": false
        },
        "genomeAssembly": {
          "description": "Genome assembly accession, e.g. \"GCA_000001405.29\". Omitted when none.",
          "type": "string"
        }
      },
      "required": [
        "upid",
        "proteomeType",
        "organism",
        "proteinCount"
      ],
      "additionalProperties": false,
      "description": "Proteome metadata."
    },
    "proteins": {
      "description": "A capped page of the proteome's proteins. Present only when include_proteins is true.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "accession": {
            "type": "string",
            "description": "UniProtKB primary accession."
          },
          "entryName": {
            "type": "string",
            "description": "UniProtKB mnemonic ID."
          },
          "proteinName": {
            "description": "Recommended protein name. Omitted when none.",
            "type": "string"
          },
          "geneNames": {
            "type": "array",
            "items": {
              "type": "string",
              "description": "A gene name or synonym."
            },
            "description": "Gene names and synonyms."
          },
          "organism": {
            "type": "object",
            "properties": {
              "scientificName": {
                "type": "string",
                "description": "Organism scientific name."
              },
              "commonName": {
                "description": "Organism common name. Omitted when none.",
                "type": "string"
              },
              "taxonId": {
                "type": "number",
                "description": "NCBI taxonomy ID."
              }
            },
            "required": [
              "scientificName",
              "taxonId"
            ],
            "additionalProperties": false,
            "description": "Source organism."
          },
          "length": {
            "type": "number",
            "description": "Canonical sequence length in residues."
          },
          "reviewed": {
            "type": "boolean",
            "description": "True for reviewed Swiss-Prot, false for unreviewed TrEMBL."
          },
          "annotationScore": {
            "type": "number",
            "description": "Annotation confidence on a 1–5 scale."
          },
          "proteinExistence": {
            "type": "string",
            "description": "Protein-existence evidence level."
          },
          "functionSnippet": {
            "description": "First function sentence(s), evidence stripped. Omitted when none.",
            "type": "string"
          }
        },
        "required": [
          "accession",
          "entryName",
          "geneNames",
          "organism",
          "length",
          "reviewed",
          "annotationScore",
          "proteinExistence"
        ],
        "additionalProperties": false,
        "description": "A protein in the proteome."
      }
    },
    "truncated": {
      "description": "True when the protein page hit the size cap — more remain via cursor.",
      "type": "boolean"
    },
    "shown": {
      "description": "Number of proteins returned in this page.",
      "type": "number"
    },
    "cap": {
      "description": "The page-size cap that was applied.",
      "type": "number"
    },
    "totalProteinsMatched": {
      "description": "Total proteins matching the (optionally filtered) proteome query.",
      "type": "number"
    },
    "cursor": {
      "description": "Forward cursor for the next protein page. Absent on the last page.",
      "type": "string"
    },
    "notice": {
      "description": "Truncation guidance when the protein page was capped — how to reach the rest (walk the cursor or narrow with the query filter).",
      "type": "string"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither upid nor taxon_id was provided. `conflicting_identifier`: Both upid and taxon_id were provided. `not_found`: The UPID or taxon has no reference proteome. Other values are possible when a failure originates below the handler.",
              "examples": [
                "missing_identifier",
                "conflicting_identifier",
                "not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "proteome"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Resolve a taxonomy record by NCBI taxon ID (e.g. 9606) or scientific name (e.g. "Homo sapiens") — provide exactly one. Returns the scientific and common name, mnemonic, rank, parent, and the full lineage. Set include_children to also fetch immediate child taxa (a separate lookup — not inline on the record). Use this to turn an organism name into the taxon ID that uniprot_search_proteins (organism_id) and uniprot_get_proteome (taxon_id) expect.

{
  "type": "object",
  "properties": {
    "taxon_id": {
      "description": "NCBI taxonomy ID, e.g. 9606. Provide this OR name, not both.",
      "type": "integer",
      "exclusiveMinimum": 0,
      "maximum": 9007199254740991
    },
    "name": {
      "description": "Organism scientific name, e.g. \"Homo sapiens\". Provide this OR taxon_id, not both. Matched against the scientific name.",
      "type": "string"
    },
    "include_children": {
      "default": false,
      "description": "When true, also fetch the immediate child taxa via a follow-up search. Defaults to false.",
      "type": "boolean"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "taxon": {
      "type": "object",
      "properties": {
        "taxonId": {
          "type": "number",
          "description": "NCBI taxonomy ID."
        },
        "scientificName": {
          "type": "string",
          "description": "Scientific name."
        },
        "commonName": {
          "description": "Common name. Omitted when none.",
          "type": "string"
        },
        "mnemonic": {
          "description": "UniProt organism mnemonic, e.g. \"HUMAN\". Omitted when none.",
          "type": "string"
        },
        "rank": {
          "type": "string",
          "description": "Taxonomic rank, e.g. \"species\"."
        },
        "parent": {
          "description": "Immediate parent taxon. Omitted at the root.",
          "type": "object",
          "properties": {
            "taxonId": {
              "type": "number",
              "description": "Parent taxon ID."
            },
            "scientificName": {
              "type": "string",
              "description": "Parent scientific name."
            }
          },
          "required": [
            "taxonId",
            "scientificName"
          ],
          "additionalProperties": false
        },
        "otherNames": {
          "description": "Synonyms and alternative spellings. Omitted when none.",
          "type": "array",
          "items": {
            "type": "string",
            "description": "An alternative name or synonym."
          }
        }
      },
      "required": [
        "taxonId",
        "scientificName",
        "rank"
      ],
      "additionalProperties": false,
      "description": "The taxonomy record."
    },
    "lineage": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "taxonId": {
            "type": "number",
            "description": "NCBI taxonomy ID of the lineage node."
          },
          "scientificName": {
            "type": "string",
            "description": "Scientific name of the lineage node."
          },
          "commonName": {
            "description": "Common name of the node. Omitted when none.",
            "type": "string"
          },
          "rank": {
            "type": "string",
            "description": "Taxonomic rank, e.g. \"phylum\", \"clade\", \"no rank\"."
          }
        },
        "required": [
          "taxonId",
          "scientificName",
          "rank"
        ],
        "additionalProperties": false,
        "description": "A node in the lineage, ordered root → near."
      },
      "description": "Full lineage from root to the taxon's near ancestor."
    },
    "children": {
      "description": "Immediate children. Present only when include_children is true.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "taxonId": {
            "type": "number",
            "description": "Child taxon ID."
          },
          "scientificName": {
            "type": "string",
            "description": "Child scientific name."
          },
          "rank": {
            "type": "string",
            "description": "Child rank."
          }
        },
        "required": [
          "taxonId",
          "scientificName",
          "rank"
        ],
        "additionalProperties": false,
        "description": "An immediate child taxon."
      }
    },
    "childCount": {
      "description": "Number of immediate children returned (when include_children is true).",
      "type": "number"
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `missing_identifier`: Neither taxon_id nor name was provided. `conflicting_identifier`: Both taxon_id and name were provided. `not_found`: The taxon ID or name did not resolve to a record. Other values are possible when a failure originates below the handler.",
              "examples": [
                "missing_identifier",
                "conflicting_identifier",
                "not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "taxon",
        "lineage"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}

Fetch the canonical amino-acid sequence (FASTA) for a UniProtKB accession, with length and the parsed header. Set include_isoforms to also return the alternatively-spliced isoform sequences. This is the cheap sequence-only path — for the full functional record use uniprot_get_entry. Accessions come from uniprot_search_proteins or uniprot_map_ids; strip any "-N" isoform suffix (P04637-2 to P04637) before calling.

{
  "type": "object",
  "properties": {
    "accession": {
      "type": "string",
      "pattern": "^(?:[OPQ][0-9][A-Z0-9]{3}[0-9]|[A-NR-Z][0-9](?:[A-Z][A-Z0-9]{2}[0-9]){1,2})$",
      "description": "UniProtKB primary accession, e.g. \"P04637\". Canonical form only — strip any \"-N\" isoform suffix."
    },
    "include_isoforms": {
      "default": false,
      "description": "When true, also return the isoform sequences. Defaults to false (canonical only).",
      "type": "boolean"
    }
  },
  "required": [
    "accession"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "accession": {
      "type": "string",
      "description": "The accession that was fetched."
    },
    "canonical": {
      "type": "object",
      "properties": {
        "header": {
          "type": "string",
          "description": "The FASTA header line (without the leading \">\"), e.g. \"sp|P04637|P53_HUMAN Cellular tumor antigen p53 OS=Homo sapiens OX=9606 GN=TP53 PE=1 SV=4\"."
        },
        "sequence": {
          "type": "string",
          "description": "The amino-acid sequence as a single string (newlines removed)."
        },
        "length": {
          "type": "number",
          "description": "Sequence length in residues."
        }
      },
      "required": [
        "header",
        "sequence",
        "length"
      ],
      "additionalProperties": false,
      "description": "The canonical sequence record."
    },
    "isoforms": {
      "description": "Isoform sequence records. Present only when include_isoforms is true and isoforms exist.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "header": {
            "type": "string",
            "description": "The FASTA header line (without the leading \">\"), e.g. \"sp|P04637|P53_HUMAN Cellular tumor antigen p53 OS=Homo sapiens OX=9606 GN=TP53 PE=1 SV=4\"."
          },
          "sequence": {
            "type": "string",
            "description": "The amino-acid sequence as a single string (newlines removed)."
          },
          "length": {
            "type": "number",
            "description": "Sequence length in residues."
          },
          "isoformId": {
            "type": "string",
            "description": "Isoform accession, e.g. \"P04637-2\"."
          }
        },
        "required": [
          "header",
          "sequence",
          "length",
          "isoformId"
        ],
        "additionalProperties": false,
        "description": "An isoform sequence record."
      }
    },
    "error": {
      "description": "Present when the call failed. Absent on success.",
      "type": "object",
      "properties": {
        "code": {
          "type": "integer",
          "minimum": -9007199254740991,
          "maximum": 9007199254740991,
          "description": "JSON-RPC error code for this failure."
        },
        "message": {
          "type": "string",
          "description": "Human-readable description of what went wrong."
        },
        "data": {
          "type": "object",
          "properties": {
            "reason": {
              "type": "string",
              "description": "Machine-readable failure mode. Declared by this tool: `not_found`: The accession has no sequence in UniProtKB. Other values are possible when a failure originates below the handler.",
              "examples": [
                "not_found"
              ]
            },
            "recovery": {
              "description": "Actionable next step for the caller.",
              "type": "object",
              "properties": {
                "hint": {
                  "type": "string"
                }
              },
              "required": [
                "hint"
              ],
              "additionalProperties": {}
            },
            "retryable": {
              "description": "Whether retrying may succeed.",
              "type": "boolean"
            }
          },
          "additionalProperties": {}
        }
      },
      "required": [
        "code",
        "message"
      ],
      "additionalProperties": {}
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false,
  "anyOf": [
    {
      "not": {
        "required": [
          "error"
        ]
      },
      "required": [
        "accession",
        "canonical"
      ]
    },
    {
      "required": [
        "error"
      ]
    }
  ]
}