InterProScan MCP Service

interproscan_mcp is a standalone FastMCP service for protein family, domain, and functional annotation. It keeps one MCP contract while supporting two backends:

• local: runs a mounted or locally installed interproscan.sh against a prepared InterProScan data directory.

• api: submits small protein FASTA jobs to the configured EMBL-EBI InterProScan REST endpoint.

• auto: the default; local is preferred, API is used when the local executable, Java runtime, data directory, or run root is unavailable.

The first version does not download, update, or package InterProScan databases. Server deployments must mount an existing installation and prepared data.

MCP Tools

• interproscan_validate_environment: validates backend policy, local runtime, data directory, writable run root, allowed input roots, application list, and API reachability.

• interproscan_list_applications: returns the bounded member-application names accepted by this MCP.

• interproscan_annotate_sequence: validates protein FASTA text, creates one job directory, annotates through the selected backend, and returns structured results.

• interproscan_annotate_fasta_file: validates an allowed FASTA file path and annotates it as one job.

Related MCP server: ESMfold MCP Server

Artifacts

Every annotation job writes under runs/jobs/<job_id>/:

• input.fasta and input_meta.json

• command.json for local jobs or request.json for API jobs

• raw local outputs such as output.tsv, or API files such as api_response.tsv

• stdout.log and stderr.log for local jobs

• results.json

• manifest.json

The manifest records input hash, input type, backend policy, backend used, fallback reason, local data path, API endpoint, effective parameters, timestamps, exit code or HTTP status, status, and artifact paths.

Configuration

Copy .env.example, configs/workstation.env, or configs/server.env and set environment variables before startup.

Key variables:

INTERPROSCAN_BACKEND=auto
INTERPROSCAN_EXECUTABLE=/opt/interproscan/interproscan.sh
INTERPROSCAN_DATA_DIR=/opt/interproscan/data
INTERPROSCAN_RUN_ROOT=./runs
INTERPROSCAN_ALLOWED_INPUT_ROOTS=./examples,./runs
INTERPROSCAN_API_ENDPOINT=https://www.ebi.ac.uk/Tools/services/rest/iprscan5
INTERPROSCAN_API_EMAIL=your-email@example.org
INTERPROSCAN_DEFAULT_THREADS=4
INTERPROSCAN_DEFAULT_TIMEOUT=120
INTERPROSCAN_MCP_TRANSPORT=stdio

Local Setup

cd D:\future\antigravity\mgi\interprosanc_mcp
.\quick_setup.ps1
.\env\Scripts\python.exe .\src\server.py

HTTP mode:

$env:INTERPROSCAN_MCP_TRANSPORT="http"
$env:INTERPROSCAN_MCP_HOST="127.0.0.1"
$env:INTERPROSCAN_MCP_PORT="8114"
$env:INTERPROSCAN_MCP_PATH="/mcp"
$env:INTERPROSCAN_BACKEND="auto"
$env:INTERPROSCAN_RUN_ROOT="D:\future\antigravity\mgi\interprosanc_mcp\runs"
.\env\Scripts\python.exe .\src\server.py

Docker

cd docker
docker compose up -d --build

Default HTTP endpoint:

http://127.0.0.1:8114/mcp

For server local mode, mount:

• INTERPROSCAN_INSTALL_ROOT: directory containing interproscan.sh

• INTERPROSCAN_DATA_ROOT: prepared data directory

• INTERPROSCAN_RUN_ROOT: writable artifacts directory

ProteinMCP

The service is registered in ProteinMCP as interproscan_mcp and interproscan.

cd D:\future\antigravity\mgi\ProteinMCP
python -m src.mcp_cli info interproscan_mcp
python -m src.mcp_cli install interproscan_mcp --no-register

Troubleshooting

• interproscan_not_found: set INTERPROSCAN_EXECUTABLE to a valid interproscan.sh.

• needs_setup: mount or configure the prepared InterProScan data directory.

• interproscan_api_unavailable: check INTERPROSCAN_API_ENDPOINT, network access, and INTERPROSCAN_API_EMAIL.

• path_not_allowed: move FASTA files under INTERPROSCAN_ALLOWED_INPUT_ROOTS.

• unsupported_application or unsupported_output_format: use the bounded values returned by interproscan_list_applications and documented output formats.