hotspot-mcp

An MCP (Model Context Protocol) server for protein binding hotspot recognition using multi-signal structural, functional, and evolutionary analysis.

What it does

Identifies binding hotspots on protein surfaces by combining 6 independent signals:

Signal	Source	What it measures
Surface	FreeSASA + DSSP	Relative SASA, secondary structure context
Pocket	fpocket / geometric	Druggability, volume, enclosure
Annotation	UniProt REST API	Known binding/active sites, domains, variants
Conservation	NCBI BLAST	Shannon entropy from multiple sequence alignment
Geometry	C-alpha distance matrix	Contact density, concavity
Flexibility	PDB B-factors	Normalized B-factor (moderate = optimal)

MCP Tools

Tool	Purpose
fetch_structure	Resolve protein ID (PDB/UniProt/name/file) and download structure
analyze_surface	Per-residue SASA + secondary structure + B-factors
detect_pockets	Find binding pockets with druggability scores
get_functional_sites	UniProt annotations (binding/active sites, domains, variants)
identify_hotspots	Primary -- full multi-signal hotspot detection pipeline
score_residues	Score user-specified residues for hotspot potential

Scoring Strategies

Strategy	Best for	Top-weighted signals
balanced	General use	Equal weighting
druggable	Small molecule pockets	Pocket (0.35), Geometry (0.20)
ppi	Protein-protein interfaces	Surface (0.30), Conservation (0.20)
conserved	Evolutionary hotspots	Conservation (0.35)

Installation

Requires Python >= 3.10 and uv.

git clone https://github.com/YOUR_USERNAME/hotspot-mcp.git
cd hotspot-mcp
uv sync

Optional dependencies

# FreeSASA (faster, more accurate SASA calculation)
uv sync --extra sasa

# fpocket (best pocket detection -- install separately)
# macOS: brew install fpocket
# Linux: apt install fpocket

# DSSP (secondary structure assignment)
# macOS: brew install dssp
# Linux: apt install dssp

Usage

As an MCP server

Add to your MCP client configuration (e.g., Claude Code .mcp.json):

{
  "mcpServers": {
    "hotspot": {
      "command": "uv",
      "args": ["--directory", "/path/to/hotspot-mcp", "run", "server.py"]
    }
  }
}

Example queries

Once connected, ask your AI assistant:

• "Find druggable hotspots on EGFR kinase domain"
• "Identify protein-protein interaction sites on hemoglobin (4HHB)"
• "Score residues 35,72,118 on 1ATP for hotspot potential"
• "What are the binding pockets on P00533?"

Running tests

uv run python test_server.py

Structure Resolution

The server accepts multiple input types:

PDB ID (e.g., "4HHB")    → download from RCSB
UniProt accession ("P00533") → SIFTS → best PDB → download
Protein name ("EGFR")    → UniProt search → SIFTS → download
File path ("/path/to.pdb")  → parse directly

Structures are cached at ~/.cache/hotspot-mcp/structures/ with a 7-day TTL.

Architecture

server.py              # FastMCP tool definitions (thin layer)
hotspot/
├── types.py           # Shared dataclasses
├── structure.py       # PDB fetching, parsing, SIFTS mapping
├── sasa.py            # SASA (FreeSASA primary, BioPython fallback)
├── secondary_structure.py  # DSSP with phi/psi fallback
├── pockets.py         # fpocket CLI or geometric fallback
├── annotations.py     # UniProt REST API client
├── conservation.py    # NCBI BLAST + Shannon entropy
└── scoring.py         # Multi-signal scoring engine
data/
└── amino_acid_properties.json  # Reference data

License

MIT