Which integrations are available for this server?

Supports deploying the bundled Protein Lab web UI to Hugging Face Spaces (Streamlit SDK): upload the repo, set app.py as the entry file, and dependencies are pulled from spaces-requirements.txt, letting the point-and-click protein analysis app be hosted publicly.

How do I use protein-tools-mcp?

1. Click on "Deploy Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@protein-tools-mcp fetch the AlphaFold model for P12345 and summarize its pLDDT confidence" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

protein-tools-mcp

by Tahsin-uv

Overview Schema Source Related Servers Discussions Admin

Python

Local

protein-tools — MCP server for general protein characterization

(+ best-in-class metal-site module)

A Model Context Protocol (MCP) server that gives any MCP-capable AI client (Cline, Claude Desktop, VS Code, etc.) general protein-characterization tools: sequence analysis (protein/DNA/RNA typing, FASTA parsing, PDB lookup), PDB/mmCIF validation, sequence extraction, pLDDT confidence summaries, GROMACS trajectory metrics, live database lookups (UniProt, AlphaFold DB, RCSB) — plus a best-in-class metal-site module (metal geometry, force-field param checks, PDB-wide metal-site index).

Built based on real protein research; stdlib-only analysis core (pdb_utils.py, seq_utils.py), so the only dependency is the mcp SDK. The metal-site module (geometry fitting, bidentate detection, PDB-wide index) is the differentiator — everything else is general protein/MD tooling any structural biologist can use.

Install

pip install protein-tools-mcp            # base: stdlib-only analysis core
pip install "protein-tools-mcp[plots]"   # + matplotlib for plot_xvg / compare_plot

Or zero-install via uv — no venv, no paths:

uvx protein-tools-mcp

(Pins to the stable 1.x SDK: mcp<2 is load-bearing since mcp>=2 renamed FastMCP to MCPServer.)

Related MCP server: mofstructure-mcp

Run / test

python test_server.py
protein-tools-setup --dry-run   # preview client registration, writes nothing

Add to an MCP client (e.g. Claude / VS Code / Cline `.mcp.json`)

Easiest — auto-register (backs up configs first, --dry-run to preview):

protein-tools-setup

Manual equivalent:

{
  "mcpServers": {
    "protein-tools": {
      "command": "uvx",
      "args": ["protein-tools-mcp"],
      "env": { "PROTEIN_TOOLS_API_KEY": "your-key-here" }
    }
  }
}

Source checkout (developers)

pip install "mcp<2"          # + "matplotlib>=3.7" for the plot tools
python test_server.py

{
  "mcpServers": {
    "protein-tools": {
      "command": "python",
      "args": ["<path-to>/protein-tools-mcp/server.py"]
    }
  }
}

Tests

13 offline suites, all self-contained — fixtures are small synthetic inputs in fixtures/ (~96 KB, no experimental data), regenerated deterministically by gen_fixtures.py:

python gen_fixtures.py        # regenerate fixtures/ (optional)
python test_units.py          # parsing correctness, metal geometry, xvg tools
python test_cif.py            # mmCIF parse + Ca2+ fixture
python test_phase12.py        # pre-flight gate, PROPKA, registry, run reports
python test_phase3.py         # plotting, premium disk cache
python test_server.py         # live 31-tool MCP round-trip over stdio
python test_setup_client.py   # client-config registration (8 checks)
python test_lab.py            # Protein Lab web-UI helpers (headless)
# plus: test_seq_utils, test_detect_sequence, test_read_fasta,
#   test_pdb_by_id, test_aa_fasta_stats, test_blast_fallback,
#   test_conservation_hint, test_structure_stats

Run state (registry DB, premium cache) lives in a per-user dir, never in the repo: %APPDATA%\protein-tools on Windows, ~/.protein-tools elsewhere, overridable via PROTEIN_TOOLS_HOME.

Protein Lab (web UI for non-programmers)

Students and wet-lab biologists can skip the MCP setup entirely — a point-and-click web app wraps the same tested analysis code:

pip install "protein-tools-mcp[lab]"   # + streamlit
protein-lab                            # opens http://localhost:8501

🔤 Sequence tab — paste letters, a FASTA record, or upload .fasta; get type verdicts, length/weight/charge/pI cards, a composition chart, and "What does this mean?" explainers + glossary.
🏗️ Structure tab — upload .pdb/.cif (or one-click demo structures); get a health verdict, chain-gap notes, and metal-site cards in plain English ("the iron atom is held by 4 protein atoms in a pyramid" instead of coordination_number: 4).
Classroom mode — demo datasets are the synthetic fixtures/, so it works fully offline; nothing is uploaded anywhere.

Deploy to Hugging Face Spaces (Streamlit SDK): upload the repo, set app.py as the entry file — dependencies come from spaces-requirements.txt. The Space should be named protein-tools-lab to keep the family visible in search. test_lab.py covers the lab helpers headlessly (no browser needed).

Tools

Structure tools accept both PDB and mmCIF (format auto-detected by .cif extension or a leading data_ record — covers AlphaFold 3 and modern RCSB depositions):

Tool	Tier	What it does
`validate_pdb`	free	Format check for PDB/mmCIF: counts, format errors, unknown residues, chain gaps, duplicate atom names, insertion codes, multi-model (NMR) notes
`metal_geometry`	free	Metal-site analysis: N/O/S donor contacts with distances + donor types, ligand-metal-ligand angles fitted to ideal geometries (octahedral, tetrahedral, ...), bidentate carboxylate chelate detection
`sequence_from_pdb`	free	One-letter sequence per chain (MD variants handled; model 1 for NMR)
`plddt_summary`	free	AlphaFold pLDDT bands + low-confidence regions; refuses to misread experimental B-factors
`xvg_summary`	free	Per-column stats for any GROMACS .xvg (energies, temperature, SASA, ...)
`rmsd_summary`	free	Equilibration assessment: drift, plateau detection, verdict
`rmsf_peaks`	free	Most flexible residues + contiguous flexible segments (mean + 1 stdev)
`md_preflight`	free	GO/NO-GO gate before MD: validation + metal sites + force-field param check
`check_metal_params`	free	Scan GROMACS .ff/.itp for metal atomtypes (sigma/epsilon or MISSING)
`propka_summary`	free	PROPKA .pka parsing: pI, extremes, protonation concerns (HIS/acid/CYS flags)
`md_run_report`	free	One-call run-dir verdict: RMSD plateau, crash scan, artifacts (GO/FINISHED/INCOMPLETE/CRASHED)
`compare_runs`	free	Side-by-side RMSD verdicts for two run dirs (apo vs holo)
`log_run` / `list_runs` / `run_details`	free	Persistent SQLite run registry - cross-session project memory
`plot_xvg`	free	Plot any .xvg to PNG (decimated for large series)
`compare_plot`	free	Overlay multiple .xvg files (e.g. apo vs holo) into one comparison PNG
`query_metal_sites`	premium (relay)	Search the hosted PDB-wide metal-site index (38,143 entries / 1,097,659 sites): filter by metal, geometry, CN range; CN-0 artifacts excluded by default. Requires `PROTEIN_TOOLS_RELAY_URL` + API key
`index_stats`	premium (relay)	Corpus stats for the hosted metal-site index (per-metal / per-geometry distributions, artifact volume). Requires `PROTEIN_TOOLS_RELAY_URL` + API key
`cache_info`	free	Inspect or clear the premium-lookup response cache
`uniprot_entry`	premium	Live UniProtKB lookup (name, organism, function, metal-binding sites), 24 h disk cache
`alphafold_plddt`	premium	Live AlphaFold DB model + confidence summary
`rcsb_entry`	premium	Live RCSB PDB entry metadata
`detect_sequence_type`	free	Detect whether a FASTA sequence is protein, DNA, RNA, ambiguous, or unknown. Accepts FASTA file path or raw FASTA text; returns type classification with confidence level and detailed notes for each sequence.
`read_fasta`	free	Read one or more sequences from a FASTA file or raw text. Returns full parsed records including sequence strings, type classifications, lengths, and heuristic UniProt accession hints. Handles multi-record FASTA, file-not-found errors, and empty input.
`pdb_by_id`	premium (local ok)	Get info about a PDB entry by its 4-character ID: checks for a local PDB/mmCIF file and if found runs validation, sequence extraction, and metal-site analysis; also fetches RCSB metadata (requires API key for full data, gracefully degrades to local-only without).
`find_pdb_by_sequence`	premium	Find PDB structures matching a protein sequence from a FASTA file or raw text via RCSB BLAST search. Parses the FASTA, verifies it's a protein sequence, then searches RCSB and returns matching PDB IDs with metadata. Requires API key.

All tools return structured errors ({"error": ..., "hint": ...}) so AI agents can self-correct (e.g. fix a bad path) instead of crashing.

Correctness notes: residue keys include PDB insertion codes (column 27); multi-MODEL (NMR) files are analyzed on model 1 only; coordination numbers count only N/O/S donor atoms; angle-based geometry fitting compares sorted observed ligand-metal-ligand angles to ideal sets (linear / trigonal-planar / tetrahedral / square-planar / TBP / square-pyramidal / octahedral).

Premium tools are gated by the PROTEIN_TOOLS_API_KEY environment variable; without it they raise a PermissionError explaining how to get a key.

Hosted relay (premium mode)

Set PROTEIN_TOOLS_RELAY_URL alongside PROTEIN_TOOLS_API_KEY to serve uniprot_entry, alphafold_plddt, rcsb_entry, query_metal_sites, and index_stats from the hosted relay (key validation, quotas, 24 h server-side caching) instead of direct upstream calls and the local index DB. Without the relay URL the server runs fully locally.

Premium tools are gated by the PROTEIN_TOOLS_API_KEY environment variable; without it they return a structured error explaining how to get a key.

Disclaimer

Free tools are research-grade (no warranty); geometry_guess is a first-pass heuristic, not a substitute for manual inspection of metal coordination.

Available Tools

31 tools

aa_compositionA

Protein physicochemistry: MW, aa composition, charge, GRAVY, pI estimate.

Parses a FASTA file or raw text (record sequence_index); rejects non-protein sequences with a structured error naming the detected type. Free; local compute.

Inputs: source (required), is_file, sequence_index. Returns: result

alphafold_plddtA

Fetch the AlphaFold DB model for a UniProt accession and summarize its pLDDT confidence profile. Premium tool (API key required). Disk-cached for 24 h; refresh=True forces a live fetch.

Inputs: accession (required), refresh. Returns: result

cache_infoA

Inspect (or with clear=True, empty) the local response cache used by the premium lookup tools (UniProt / AlphaFold DB / RCSB).

Inputs: clear. Returns: result

check_metal_paramsA

Scan a GROMACS force-field directory or .itp/.ff file for metal atomtypes (e.g. ZN, FE) and report sigma/epsilon or MISSING entries.

Run this BEFORE pdb2gmx on any metalloprotein - a missing metal atomtype will kill the topology build.

Inputs: ff_path (required), metals. Returns: result

compare_plotB

Overlay the value column of several .xvg files (comma-separated paths, e.g. apo vs holo RMSD) into one comparison PNG.

Inputs: xvg_paths (required), title, labels, out_png, +2 more. Returns: result

compare_runsC

Side-by-side RMSD verdicts for two run directories (e.g. apo vs holo): plateau status, late-run means, drift, and relative difference.

Inputs: dir_a (required), dir_b (required). Returns: result

conservation_hintA

Conservation / functional hint for a UniProt entry: feature table.

Reuses the premium UniProt fetch (same key + relay/local path as uniprot_entry): feature types grouped (Metal binding / Active site / Binding site / Disulfide bond / Mutagenesis / Natural variant) with 1-based canonical positions. Align your PDB sequence first (sequence_from_pdb + read_fasta) before mapping positions.

Inputs: accession_or_id (required). Returns: result

detect_sequence_typeA

Detect whether a FASTA sequence is protein, DNA, RNA, ambiguous, or unknown.

Accepts a FASTA file path (is_file=True) or raw FASTA text (is_file=False). Returns the type classification with confidence and detailed notes.

Inputs: source (required), is_file, sequence_index. Returns: result

fasta_statsB

Multi-FASTA summary: N50, length stats, per-type counts, GC%.

GC% is computed over DNA records only (null with a note when none). Free; local compute.

Inputs: source (required), is_file. Returns: result

find_pdb_by_sequenceA

Find PDB structures matching a protein, DNA, or RNA sequence.

Parses the FASTA, maps the detected type to the RCSB sequence search (protein→blastp, dna/rna→blastn), and returns matching PDB IDs. Ambiguous/unknown sequences are rejected with a structured error. Requires an API key (premium tool).

Inputs: source (required), is_file, max_results, sequence_index. Returns: result

index_statsB

Corpus-level stats for the PDB-wide metal-site index (premium: requires the hosted relay): entry/site counts, per-metal and per-geometry distributions, artifact volume.

Inputs: db_path. Returns: result

list_runsA

List recent registry entries (newest first), optionally filtered by kind. Use this at session start to recall project history.

Inputs: kind, limit. Returns: result

log_runA

Record a run/event in the persistent project registry (cross-session memory). kind: e.g. 'md_report', 'prep', 'hypothesis'. metrics/paths accept JSON strings or plain text. Returns the registry id.

Inputs: kind (required), notes, paths, run_id, +2 more. Returns: result

md_preflightA

MD pre-flight gate for a structure: PDB/mmCIF validation + metal-site detection + force-field metal parameter check. Returns GO or NO-GO with blocking issues. Treat NO-GO as a hard stop before any GPU/MD launch.

Inputs: pdb_path (required), ff_dir. Returns: result

md_run_reportA

Analyze a GROMACS run directory: RMSD verdicts, other .xvg inventory, md.log crash scan, artifact presence, and an overall verdict (GO / FINISHED / INCOMPLETE / CRASHED). Optionally logs to the registry.

Inputs: run_dir (required), log. Returns: result

metal_geometryB

Analyze metal-binding sites in a PDB file.

Finds all atoms of the given metal element (e.g. FE, ZN, MN, MG), lists coordinating ligand atoms (N/O/S donors) with distances and donor types, computes ligand-metal-ligand angles fitted to ideal geometries (octahedral, tetrahedral, ...), and flags bidentate carboxylate chelates.

Inputs: pdb_path (required), metal_element, cutoff_angstrom. Returns: result

pdb_by_idB

Get info about a PDB entry by its 4-character PDB ID.

Checks if a local PDB/mmCIF file exists for the ID, and if so returns local structure info (validation, sequence, metal sites). Also fetches RCSB metadata if an API key is set (premium tool).

Inputs: pdb_id (required), refresh. Returns: result

plddt_summaryA

Summarize AlphaFold-style pLDDT confidence from B-factor columns.

Reports mean, confidence bands (>90/70-90/50-70/<50), and low-confidence regions. Refuses to interpret experimental-structure B-factors as pLDDT.

Inputs: pdb_path (required). Returns: result

plot_xvgB

Plot every series of a GROMACS .xvg file against column 0 into a PNG (large series are decimated to <=5000 points). Returns the output path.

Inputs: xvg_path (required), title, out_png, y_from_zero. Returns: result

propka_summaryA

Parse a PROPKA .pka output: pI, per-residue-type counts, pKa extremes, and protonation-state concerns (HIS near pH 7, raised acids, CYS 99.99 disulfide markers) - exactly the decisions pdb2gmx protonation needs.

Inputs: pka_path (required). Returns: result

query_metal_sitesA

Search the PDB-wide metal-site index (premium: requires the hosted relay — set PROTEIN_TOOLS_RELAY_URL + PROTEIN_TOOLS_API_KEY).

Filter by metal, geometry class, coordination-number range. Defaults exclude CN-0 isolated-ion artifacts and CN-1; set min_cn=1 to see unusual CN-1 chemistry, include_artifacts=True to also return CN-0 rows. Examples: tetrahedral Cys4 zinc fingers (metal='ZN', geometry='tetrahedral'), catalytic zinc (metal='ZN', min_cn=4, max_cn=6).

Inputs: metal (required), limit, max_cn, min_cn, +3 more. Returns: result

rcsb_entryA

Fetch RCSB PDB entry metadata: title, experimental method, resolution, deposit date. Premium tool (API key required). Disk-cached for 24 h; refresh=True forces a live fetch.

Inputs: pdb_id (required), refresh. Returns: result

read_fastaB

Read one or more sequences from a FASTA file or text.

Accepts a FASTA file path (is_file=True) or raw FASTA text (is_file=False). Returns the full parsed records including sequences, types, and metadata.

Inputs: source (required), is_file, normalize, sequence_index. Returns: result

rmsd_summaryA

Assess equilibration from a GROMACS RMSD .xvg file: drift between the first and last 10% of frames, plateau detection, and an equilibrated / not-equilibrated verdict.

Inputs: xvg_path (required). Returns: result

rmsf_peaksA

Extract the most flexible residues/atoms from a GROMACS RMSF .xvg file: top-N highest values and contiguous flexible segments (above mean + 1 stdev).

Inputs: xvg_path (required), top_n. Returns: result

run_detailsC

Full record for one registry entry, by numeric id or run_id.

Inputs: rid (required). Returns: result

sequence_from_pdbA

Extract one-letter amino-acid sequences per chain from a PDB file (handles MD protonation variants; for multi-model files uses model 1).

Inputs: pdb_path (required). Returns: result

structure_statsA

General structure summary: atoms, residues, chains, gaps, altLocs.

Accepts PDB or mmCIF (auto-detected). Free; local compute.

Inputs: pdb_path (required). Returns: result

uniprot_entryA

Fetch a UniProtKB entry: protein name, organism, function, length, sequence, and metal-binding annotations. Premium tool (API key required). Results are disk-cached for 24 h; refresh=True forces a live fetch.

Inputs: accession (required), refresh. Returns: result

validate_pdbA

Validate a PDB or mmCIF structure file (AlphaFold 3 / RCSB) for downstream use (MD prep, docking, analysis).

Reports atom/residue/chain counts, fixed-column format errors, non-standard residues, altLocs, chain gaps, duplicate atom names, insertion-code residues, and multi-model (NMR) notes. Always run this before feeding a structure into a pipeline.

Inputs: pdb_path (required). Returns: result

xvg_summaryA

Summarize any GROMACS .xvg file (RMSD, energies, temperature, SASA...): per-column min/max/mean/stdev/first/last plus title and axis labels.

Inputs: xvg_path (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

Deploy Server

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

TDQS

B3.2/5.0

Scored 2026-10-20 12:11 across 31 tools

Disambiguation4/5

Most tools target distinct tasks (validation, metal geometry, xvg parsing, registry, premium lookups), but a few overlap: pdb_by_id and rcsb_entry both retrieve PDB metadata, while structure_stats overlaps with validate_pdb on basic counts. Aggregate tools like md_preflight also partially duplicate their component checks, though descriptions clarify their gate role.

Naming Consistency3/5

All names use snake_case, which is good, but the verb style is inconsistent: some are verb_noun (list_runs, validate_pdb, plot_xvg), while many are noun_noun (run_details, structure_stats, plddt_summary). This mixed convention is readable but not a predictable single pattern.

Tool Count2/5

With 31 tools, the surface is far above the typical 3-15 range and even above the 25+ 'too many' threshold. While the domain is broad (structure, MD, sequence, registry, premium DB), the sheer number increases selection burden and suggests the server should be split or consolidated.

Completeness3/5

The set covers many structure/MD analyses, but there are notable gaps: no sequence alignment tool despite conservation_hint instructing users to align PDB and UniProt sequences, no PDB coordinate download (validate_pdb requires a local file), and the registry lacks update/delete operations. These gaps force agents to use external tools or work around stated workflows.

Resources

Related MCP Connectors

Axon NeuroAutomata
ai.axonagentic
Protein analysis: ESM-2/ESMC embeddings, mutation scoring, landscape scans, ESMFold structure.
Bioinformatics Biology & Medicine
2
https://mcp.neuroautomata.axonagentic.ai/mcp
Elnora MCP Server
io.github.Elnora-AI
AI-powered bioprotocol optimization — generate, search, and manage lab protocols via MCP
Biology & Medicine Research & Data App Automation
23
https://mcp.elnora.ai/mcp
JapanFold
io.github.japanfold
Fold proteins, co-fold ligands with binding affinity, design binders and embed sequences.
Bioinformatics Biology & Medicine AI & Machine Learning
1
https://api.japanfold.aiand.com/mcp
A2A PeptidesB
io.github.A2A-Peptides
Agent-to-Agent (A2A) + Model Context Protocol (MCP) hub for peptides.
E-commerce & Retail Biology & Medicine Payments & Billing
201
https://mcp.a2a-peptides.ai/mcp

Related MCP Servers

AlphaFold MCP Server
Bioinformatics Research & Data Knowledge & Memory
Augmented-Nature
A
license
B
quality
D
maintenance
A comprehensive Model Context Protocol (MCP) server that provides access to the AlphaFold Protein Structure Database through a rich set of tools and resources for protein structure prediction analysis.
Updated a year ago (2025-12-21 10:07 UTC)
19
37
MIT
mofstructure-mcp
lichman0405
F
license
Not graded
quality
D
maintenance
An MCP server for deconstructing and analyzing Metal-Organic Framework (MOF) structures, including SBU and ligand identification, guest removal, and COF stacking analysis. It enables AI agents to perform automated chemical informatics and structural characterization on crystal structures via CIF files.
Updated 8 months ago (2026-03-16 02:17 UTC)
1
-
ESMfold MCP Server
Bioinformatics Biology & Medicine Research & Data
MacromNex
F
license
Not graded
quality
D
maintenance
Enables protein sequence analysis and structure prediction by extracting ESM-2 embeddings and batch processing FASTA files via Docker. It provides tools for large-scale embedding extraction, job monitoring, and model management within an MCP-compatible environment.
Updated 9 months ago (2026-02-22 15:25 UTC)
-
MCPymol
Biology & Medicine Bioinformatics
chemrich
A
license
C
quality
B
maintenance
A Model Context Protocol server that lets you drive PyMOL with natural language, enabling structure loading, analytical views, measurements, and protein exploration through AI assistants.
Updated 6 days ago (2026-11-05 05:09 UTC)
135
134 PyPI
16
MIT

protein-tools — MCP server for general protein characterization

(+ best-in-class metal-site module)

Install

Run / test

Add to an MCP client (e.g. Claude / VS Code / Cline .mcp.json)

Source checkout (developers)

Tests

Protein Lab (web UI for non-programmers)

Tools

Hosted relay (premium mode)

Disclaimer

Available Tools

Tool Schema Changelog

TDQS

Resources

Related MCP Connectors

Related MCP Servers

AlphaFold MCP Server

mofstructure-mcp

ESMfold MCP Server

MCPymol

Add to an MCP client (e.g. Claude / VS Code / Cline `.mcp.json`)