uniprot-mcp-server

uniprot-mcp-server: search proteins

uniprot_search_proteins

Read-onlyIdempotent

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 search both tiers together (for TrEMBL only, put reviewed:false in query). The organism_id and reviewed filters apply to the whole query. Request facets (e.g. reviewed, model_organism) for server-side count breakdowns. Results page forward with an opaque cursor; UniProtKB has no offset paging. An inactive accession the query matches (merged, demerged, or deleted) comes back in inactive[] with the accessions that replace it, never as a result. This is the discovery entry point — chain results[].accession into uniprot_get_entry for full records, or uniprot_get_sequence for FASTA.

Tool call template

This tool declares no required parameters. Add optional parameters from the input schema as needed.

{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "tools/call",
  "params": {
    "arguments": {},
    "name": "uniprot_search_proteins"
  }
}

Input Schema

Name	Required	Description
`size`	No	Number of hits per page (max 500). Omit for the server default.
`query`	No	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.
`cursor`	No	Opaque forward cursor from this tool for the same exact effective query and filters. Size, fields, and facets may change. Older raw cursors are rejected; restart without cursor. Random access to page N is not supported.
`facets`	No	Comma-separated upstream facet names for count breakdowns, e.g. "reviewed,model_organism,proteins_with". Returns a facets array alongside the hits.
`fields`	No	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.
`reviewed`	No	Restrict to reviewed Swiss-Prot entries. Defaults to true (curated only). false applies no tier filter, returning reviewed and unreviewed TrEMBL entries together; for TrEMBL only, put reviewed:false in query. Ignored when query already contains a reviewed: clause; plain text never overrides this filter.
`organism_id`	No	Restrict to an NCBI taxon and its descendants, including strains and subspecies, e.g. 9606 for human or 562 for E. coli. Applies taxonomy_id to the whole query; use an explicit organism_id: clause in query for an exact taxon. Resolve names with uniprot_get_taxonomy.
`text_search`	No	Plain-language search across protein names, gene names, and function, e.g. "kinase apoptosis". Punctuation and uppercase AND/OR/NOT are searched as text, with UniProt tokenization; use query for operators and field syntax. Provide this OR query, not both.

Output Schema

Name	Required	Description
`error`	No	Present when the call failed. Absent on success.
`cursor`	No	Forward cursor for the next page. Absent on the last page.
`facets`	No	Upstream facet count breakdowns. Present only when facets were requested.
`notice`	No	Guidance when nothing matched, distinguishing plain text from a structured query and suggesting how to broaden.
`results`	No	Matching active protein hits for this page. Inactive accessions are in inactive.
`inactive`	No	Matching accessions that are inactive in UniProtKB (merged, demerged, or deleted) — not proteins to read, but pointers to the accessions that replace them. Present only when the page held any.
`totalResults`	No	Total matches for the query before pagination (from the upstream result count), inactive accessions included.
`effectiveQuery`	No	The query as the server assembled and sent it to UniProtKB.

Schema Changelog

Changes observed during successful MCP inspections.

Changed5 schema fields changedNov 4, 2026

changedInput schema / properties / organism_id / description

Previous value: -"Restrict to an NCBI taxon ID, e.g. 9606 for human. A convenience filter ANDed onto the whole query; resolve names with uniprot_get_taxonomy."New value: +"Restrict to an NCBI taxon and its descendants, including strains and subspecies, e.g. 9606 for human or 562 for E. coli. Applies taxonomy_id to the whole query; use an explicit organism_id: clause in query for an exact taxon. Resolve names with uniprot_get_taxonomy."

changedInput schema / properties / reviewed / description

Previous value: -"Restrict to reviewed Swiss-Prot entries. Defaults to true (curated only). false applies no tier filter, returning reviewed and unreviewed TrEMBL entries together; for TrEMBL only, put reviewed:false in query. Ignored when query or text_search already contains a reviewed: clause."New value: +"Restrict to reviewed Swiss-Prot entries. Defaults to true (curated only). false applies no tier filter, returning reviewed and unreviewed TrEMBL entries together; for TrEMBL only, put reviewed:false in query. Ignored when query already contains a reviewed: clause; plain text never overrides this filter."

changedInput schema / properties / text_search / description

Previous value: -"Plain-language search across protein names, gene names, and function, e.g. \"kinase apoptosis\". Provide this OR query, not both."New value: +"Plain-language search across protein names, gene names, and function, e.g. \"kinase apoptosis\". Punctuation and uppercase AND/OR/NOT are searched as text, with UniProt tokenization; use query for operators and field syntax. Provide this OR query, not both."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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. `invalid_query`: The query or text_search has unbalanced parentheses (rejected before any request), or UniProtKB rejected the query, text_search, fields, or facets value — the message names the rejected value. `invalid_cursor`: The cursor is malformed, from an older version, belongs to another tool or effective query, or UniProt could not continue from it (HTTP 500). Other values are possible when a failure originates below the handler."New value: +"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. `invalid_query`: The query has unbalanced parentheses (rejected before any request), or UniProtKB rejected the query, text_search, fields, or facets value — the message names the rejected value. `invalid_cursor`: The cursor is malformed, from an older version, belongs to another tool or effective query, or UniProt could not continue from it (HTTP 500). Other values are possible when a failure originates below the handler."

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nothing matched — echoes the query and suggests how to broaden."New value: +"Guidance when nothing matched, distinguishing plain text from a structured query and suggesting how to broaden."

Changed2 schema fields changedOct 22, 2026

changedInput schema / properties / cursor / description

Previous value: -"Opaque forward-pagination cursor from a prior response. Walk pages with this; random access to page N is not supported."New value: +"Opaque forward cursor from this tool for the same exact effective query and filters. Size, fields, and facets may change. Older raw cursors are rejected; restart without cursor. Random access to page N is not supported."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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. `invalid_query`: The query or text_search has unbalanced parentheses (rejected before any request), or UniProtKB rejected the query, text_search, fields, or facets value — the message names the rejected value. `invalid_cursor`: UniProt could not continue from the cursor (it answered HTTP 500) — the cursor is malformed or truncated. Other values are possible when a failure originates below the handler."New value: +"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. `invalid_query`: The query or text_search has unbalanced parentheses (rejected before any request), or UniProtKB rejected the query, text_search, fields, or facets value — the message names the rejected value. `invalid_cursor`: The cursor is malformed, from an older version, belongs to another tool or effective query, or UniProt could not continue from it (HTTP 500). Other values are possible when a failure originates below the handler."

Changed7 schema fields changedOct 14, 2026

changedInput schema / properties / organism_id / description

Previous value: -"Restrict to an NCBI taxon ID, e.g. 9606 for human. A convenience filter ANDed onto the query; resolve names with uniprot_get_taxonomy."New value: +"Restrict to an NCBI taxon ID, e.g. 9606 for human. A convenience filter ANDed onto the whole query; resolve names with uniprot_get_taxonomy."

changedInput schema / properties / reviewed / description

Previous value: -"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."New value: +"Restrict to reviewed Swiss-Prot entries. Defaults to true (curated only). false applies no tier filter, returning reviewed and unreviewed TrEMBL entries together; for TrEMBL only, put reviewed:false in query. Ignored when query or text_search already contains a reviewed: clause."

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"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."New value: +"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. `invalid_query`: The query or text_search has unbalanced parentheses (rejected before any request), or UniProtKB rejected the query, text_search, fields, or facets value — the message names the rejected value. `invalid_cursor`: UniProt could not continue from the cursor (it answered HTTP 500) — the cursor is malformed or truncated. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "missing_query",
-  "conflicting_query"
-]New value: +[
+  "missing_query",
+  "conflicting_query",
+  "invalid_query",
+  "invalid_cursor"
+]

addedOutput schema / properties / inactive

Added value: +{
+  "description": "Matching accessions that are inactive in UniProtKB (merged, demerged, or deleted) — not proteins to read, but pointers to the accessions that replace them. Present only when the page held any.",
+  "items": {
+    "additionalProperties": false,
+    "description": "An inactive accession the query matched, with where to go instead.",
+    "properties": {
+      "accession": {
+        "description": "The inactive UniProtKB accession the query matched.",
+        "type": "string"
+      },
+      "deletedReason": {
+        "description": "Why UniProt deleted the entry, when it says. Present on DELETED only.",
+        "type": "string"
+      },
+      "reason": {
+        "description": "UniProt inactiveReasonType: MERGED, DEMERGED, or DELETED. Omitted when UniProt names none.",
+        "type": "string"
+      },
+      "replacedBy": {
+        "description": "Accessions that replace it — the merge target (MERGED) or the demerge products (DEMERGED). Look these up instead.",
+        "items": {
+          "description": "A replacement UniProtKB accession.",
+          "type": "string"
+        },
+        "type": "array"
+      },
+      "uniParcId": {
+        "description": "UniParc ID that still holds the sequence, when UniProt gives one.",
+        "type": "string"
+      }
+    },
+    "required": [
+      "accession"
+    ],
+    "type": "object"
+  },
+  "type": "array"
+}

changedOutput schema / properties / results / description

Previous value: -"Matching protein hits for this page."New value: +"Matching active protein hits for this page. Inactive accessions are in inactive."

changedOutput schema / properties / totalResults / description

Previous value: -"Total matches for the query before pagination (from the upstream result count)."New value: +"Total matches for the query before pagination (from the upstream result count), inactive accessions included."

First observedAug 22, 2026

TDQS

A4.8/5.0

Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, it discloses the reviewed-default trap and why it exists (TrEMBL ~30x more numerous), that filters apply to the whole query, that paging is opaque forward-only with no offset paging, and that merged/demerged/deleted accessions surface in inactive[] rather than as results — none of which the annotations convey.

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

Conciseness4/5

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

Front-loaded with the core action and the two-parameter fork before the finer points, and nearly every sentence carries decision-relevant information. Some redundancy with the schema descriptions (reviewed default, text_search vs query) makes the single dense paragraph a bit heavier than necessary.

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

Completeness5/5

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

For an 8-parameter discovery tool with an output schema, the description covers everything an agent must know to call it correctly: mode selection, default hazards, facet requests, paging model, and the inactive[] edge case that would otherwise be mistaken for a failure.

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

Parameters4/5

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

Schema coverage is 100%, so baseline is 3; the description still adds real meaning on top of it — the mutual exclusivity rule ("exactly one is required") is stronger than the schema's "not both", and it clarifies that organism_id/reviewed scope the entire query rather than the last clause. It largely restates the reviewed and text_search semantics already in the schema, which keeps it short of a 5.

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

Purpose5/5

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

"Search UniProtKB and return curated protein records" gives a specific verb and resource, and "This is the discovery entry point" plus the explicit chaining to uniprot_get_entry and uniprot_get_sequence separates it from every sibling tool.

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

Usage Guidelines5/5

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

It explicitly routes the agent: text_search for the "80% case", query for Lucene field syntax, exactly one required. It also states the escape hatch for the surprising default ("for TrEMBL only, put reviewed:false in query") and names the follow-up tools, so no inference is needed.

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

All uniprot-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

uniprot-mcp-server: search proteins

Tool call template

Input Schema

Output Schema

Schema Changelog

TDQS

Glama MCP Gateway

Resources