interpro-mcp-server

Overview

Protein families, domains, repeats, and functional sites from InterPro and the member databases it integrates (Pfam, PROSITE, SMART, CDD, PANTHER, and others), read through the keyless EMBL-EBI InterPro API. Search entries, read their full metadata, map a UniProt protein's annotations to residue coordinates, walk Pfam, CDD, and PIRSF clans, and find proteins that carry a signature. Runs over STDIO or Streamable HTTP, with no credentials to configure.

Tools

Related MCP server: mcp-uniprot

Capability reference

interpro_search_entries tool

• sourceDatabase (default interpro) plus optional query (1-300 characters), entryType, goTerm (GO:0003677 form), goCategory (P, F, C), and integratedInto (an IPR accession, member databases only); no filter is required, so omitting all of them browses the database

• Cursor-paged, limit 1-100 (default 20); returns entries, page (total, returned, hasMore, nextCursor), and the applied query

interpro_get_entry tool

• accession required; sourceDatabase is inferred from standard accession prefixes when omitted. A set accession (CL…) fails as entry_not_found and points to interpro_get_clan

• Wikipedia thumbnails are omitted unless includeThumbnail: true, and a notice reports what was left out

• A withdrawn record fails as entry_withdrawn with its deletion date and short name

interpro_get_protein_domains tool

• Canonical six- or ten-character UniProt accession (no isoform suffix); optional residuePosition (1-based, inclusive) keeps every match with a fragment covering it, with all of that match's fragments intact; includeExtraFeatures adds predicted features such as disorder and transmembrane regions

• Large maps arrive in segments of whole matches within a 100,000-byte response budget, following coverage.nextCursor until hasMore is false. The first segment carries the protein metadata, and an empty segment cannot establish that nothing is annotated

• Discontinuous fragments, models, and upstream scores are kept as returned; residue_out_of_range and protein_not_found are typed failures

interpro_get_clan tool

• accession for a Pfam (CL0016), CDD (cl21453), or PIRSF (PIRSF000047) set, with sourceDatabase (pfam, cdd, pirsf) inferred from the prefix; members page by cursor, limit 1-100 (default 20)

• includeRelationships: true adds the relationship graph in slices that fit the response budget; relationshipsPage.nextOffset goes back in as relationshipOffset, which needs includeRelationships set

• includeThumbnail works as on interpro_get_entry; a missing set is clan_not_found

interpro_find_proteins_by_domain tool

• accession plus optional sourceDatabase; taxonId (NCBI, default 9606) and reviewedOnly (default true; false covers reviewed and unreviewed proteins) are echoed in query

• Cursor-paged, limit 1-50 (default 20); each result keeps the protein summary, matched entry locations, and taxon lineage

• No hits is a success with a notice, since the API answers an unknown entry, an unknown taxon, and an empty intersection the same way

interpro_list_reference tool

• topic required: databases, entry_types, accession_patterns, taxa, or release. The first four are local and make no network call; taxa lists common examples, not every taxon

• release reads the current InterPro version, date, and per-database entry counts, and fails as release_changed if the two upstream responses disagree on the version

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

InterPro-specific:

• 15 database slugs (interpro, pfam, prosite, profile, smart, cdd, panther, cathgene3d, ssf, ncbifam, hamap, prints, pirsf, sfld, antifam) and 11 entry types, with the entry database inferred from standard accession prefixes and conflicting routes rejected locally

• One process-wide request pacer at one upstream request per second, a 50-second budget per tool call covering pacing, retries, and every request, and a 4 MiB cap on upstream responses

• Upstream HTTP/1.1 client that handles the API's bodyless 204 responses, which native fetch rejects on Node

• Sparse upstream metadata passes through as null or omitted rather than filled in

Agent-friendly output:

• content[] carries the complete output as compact JSON plus an index of every URL as a link and every image as an image, so clients that read only one surface get the same data

• Opaque cursors bound to their query, with a notice naming the exact next call whenever a result is partial

• Typed failure reasons (entry_not_found, invalid_cursor, upstream_rate_limited, and others) each paired with a recovery hint

• Coordinates describe sequence annotation, not pathogenicity or clinical significance

Getting started

Add the following to your MCP client configuration file. No API key is needed.

{
  "mcpServers": {
    "interpro-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/interpro-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "interpro-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/interpro-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "interpro-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/interpro-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/interpro-mcp-server.git

2. Navigate into the directory:

cd interpro-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env

Configuration

The server defines no variables of its own; the InterPro API is keyless. These framework variables are the ones most often set:

See .env.example for the common framework overrides.

Running the server

Local development

• Build and run the production version:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:http
  # or
  bun run start:stdio

• Run checks and tests:

  bun run devcheck  # Lints, formats, type-checks, and more
  bun run test      # Runs the test suite

Project structure

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches, with no try/catch in tool logic

• Use ctx.log for request-scoped logging

• Register new tools in the createApp() array in src/index.ts

• Wrap external API calls: validate raw, normalize to the domain type, return the output schema; never fabricate missing fields

Contributing

Issues are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

This project is licensed under the Apache 2.0 License. See the LICENSE file for details.

Data comes from InterPro and its member databases through the EMBL-EBI API. Licensing varies by member database, so attribute InterPro and the originating database; see InterPro's license page and the EMBL-EBI terms of use.