io.github.cyanheads/interpro-mcp-server

@cyanheads/interpro-mcp-server

Search InterPro entries, map protein domains and functional sites, and find proteins by domain via MCP. STDIO or Streamable HTTP.

6 Tools

Public Hosted Server: https://interpro.caseyjhand.com/mcp

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, Streamable HTTP, or the public hosted endpoint above, with no credentials to configure.

Tools

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
• goTerm and goCategory require sourceDatabase: "interpro"; choose one GO filter per call. Combining them fails before network access because upstream ignores the category when a term is supplied. For member signatures, search InterPro with the GO filter, then read member_databases with interpro_get_entry or search the member database with integratedInto set to the matching InterPro accession
• Cursor-paged, positive integer limit capped at 100 (default 20); larger requests are clamped with a notice. Returns entries, page (total, returned, limit, hasMore, nextCursor), and the applied query; page.limit is the effective page size

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
• Optional sections selects from description, hierarchy, member_databases, go_terms, literature, cross_references, wikipedia, counters, and overlaps_with. Core metadata and unknown upstream fields remain; omitted sections returns full detail
• Optional positive integer overlapLimit pages complete overlaps_with records; overlapOffset requires it, starts at zero, and advances using overlapsPage.nextOffset. Paging requires overlaps to be retained. Selection and omissions are disclosed; absent or null overlap data stays distinct from an empty list
• Wikipedia thumbnails are omitted unless includeThumbnail: true, and a notice reports what was left out
• entry.descriptionText adds readable text with paragraph, list, and table boundaries alongside the unchanged source entry.description, including its HTML and annotation flags. It is omitted when description is excluded or no readable text is supplied
• 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
• includeResidueAnnotations: true adds residueAnnotations, the provider's functional rule annotations. A residue filter keeps each whole rule with any fragment covering the position, preserving descriptions, residue letters, locations, and provenance
• Large maps arrive in segments of whole records within a 100,000-byte response budget: matches, requested extra features, then requested residue rules. Follow coverage.nextCursor until hasMore is false. The first segment carries protein metadata; an empty segment cannot establish that nothing is annotated. Residue annotations are omitted until their stage is reached, while {} means that stage returned no selected rules
• 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, with positive integer limit capped at 100 (default 20). Larger requests are clamped with a notice; page.limit reports the effective size
• 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
• Optional isFragment selects proteins annotated as fragments (true) or not annotated as fragments (false); omit it to include both. False does not establish sequence completeness. Explicit selections appear in query and must stay unchanged when following cursors
• Optional architectureId accepts protein.ida_accession from interpro_get_protein_domains: a 40-character hexadecimal identifier, normalized lowercase. Equality means the provider's Pfam architecture grouping, not equivalent function. Keep it unchanged when following cursors
• Cursor-paged, positive integer limit capped at 50 (default 20); larger requests are clamped with a notice, and page.limit is the effective size. Ordinary results keep the protein summary, matched entry locations, taxon lineage, and native extra_fields.is_fragment annotation; missing or null status remains unknown. Architecture-filtered rows retain native extra_fields.ida_id when supplied and use detailAvailability to distinguish unavailable entry/taxon details from actual empty arrays
• 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

Public Hosted Instance

A public instance is available at https://interpro.caseyjhand.com/mcp — no installation required. It serves Streamable HTTP; each client takes its own config shape.

For Claude Code:

claude mcp add --transport http interpro-mcp-server https://interpro.caseyjhand.com/mcp

For Cline (cline_mcp_settings.json):

{
  "mcpServers": {
    "interpro-mcp-server": {
      "type": "streamableHttp",
      "url": "https://interpro.caseyjhand.com/mcp"
    }
  }
}

For Cursor (mcp.json):

{
  "mcpServers": {
    "interpro-mcp-server": {
      "url": "https://interpro.caseyjhand.com/mcp"
    }
  }
}

Claude Desktop adds remote servers under Settings → Connectors.

Self-Hosted / Local

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

1. Navigate into the directory:

cd interpro-mcp-server

1. Install dependencies:

bun install

1. 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.