# smaniches/alphafold-sovereign-mcp [Health: Active]

**Category:** Biology, Medicine and Bioinformatics  
**Repository:** https://github.com/smaniches/alphafold-sovereign-mcp  
**GitHub Stars:** 4  
**Views:** 5  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/smaniches-alphafold-sovereign-mcp

## Description
AlphaFold MCP server integrating AlphaFold DB with eight additional public biomedical data sources, backed by a local SQLite knowledge graph for structural-confidence, variant, disease/phenotype, drug-target, and orthology workflows. uvx alphafold-sovereign-mcp

## Tools
Capabilities this server exposes over MCP:

- **lookup_disease** — Retrieve a disease record from the MONDO unified disease ontology.

Returns the canonical MONDO entry with:
- Disease name, definition, synonyms
- ICD-10 / ICD-11 codes (for clinical coding / EHR integration)
- OMIM, Orphanet, MeSH, DOID cross-references
- Immediate parent and child terms in the MONDO hierarchy

Example: ``lookup_disease(mondo_id='MONDO:0004995')``
returns the record for coronary artery disease.
- **search_diseases** — Search for diseases by name or keyword using the MONDO ontology.

Returns a ranked list of matching diseases with MONDO IDs and
cross-references.  Useful for resolving a clinical term to a
canonical identifier before querying targets or phenotypes.

Example: ``search_diseases(query='breast cancer', limit=5)``
- **lookup_phenotype** — Retrieve an HPO phenotype term with associated disease annotations.

Returns:
- Phenotype label, definition, synonyms
- Diseases annotated with this phenotype (from HPO + OMIM + Orphanet)
- Parent phenotype terms

Example: ``lookup_phenotype(hpo_id='HP:0001250')``
returns the Seizure phenotype with ~400 associated diseases.
- **get_gene_phenotype_profile** — Return all HPO phenotypes associated with a gene, plus gnomAD constraint.

Useful for understanding the clinical consequences of variants in a gene
before requesting structural context.

Returns:
- HPO phenotypes linked to the gene (from HPO association database)
- gnomAD LOEUF / pLI constraint scores
- Interpretation of constraint (haploinsufficient / tolerant / moderate)

Example: ``get_gene_phenotype_profile(gene_symbol='SCN1A')``
- **get_disease_targets** — Return top protein targets for a disease with Open Targets evidence scores.

Evidence score breakdown (0–1 per data type):
- ``genetic_association``: GWAS + rare-variant signals
- ``somatic_mutation``: Cancer somatic variant evidence
- ``known_drug``: Approved or clinical-stage drugs
- ``affected_pathway``: Pathway membership (Reactome, SIGNOR)
- ``literature``: Text-mining evidence (Europe PMC)
- ``animal_model``: Knockout / model organism phenotypes
- ``rna_expression``: Differential expression evidence

Example: ``get_disease_targets(disease_id='MONDO:0007254', limit=15)``
returns top 15 targets for breast carcinoma.
- **get_target_diseases** — Return all diseases associated with a protein target via Open Targets.

Accepts a UniProt accession and returns the full disease landscape
for that target — essential for target-validation and indication-expansion.

Example: ``get_target_diseases(uniprot_id='P04637')``
returns all diseases associated with TP53 / p53.
- **get_common_disease_targets** — Profile the top drug targets for a curated set of common diseases in one call.

Use this for a fast landscape scan across a whole disease area: given a
``category`` (e.g. 'oncology'), it looks up the curated MONDO diseases in that
category and returns each one's top Open Targets evidence-scored targets, in
parallel. To profile a single disease you already have a MONDO ID for, use
``get_disease_targets`` instead — this tool is its category-level,
multi-disease counterpart and does not accept a raw MONDO ID.

Queries Open Targets live. Returns a JSON string with the ``category``, the
number of diseases profiled, and a ``profile`` object mapping each disease to
its MONDO ID and top targets (per-disease errors are reported inline, not
raised). Returns a JSON error object listing the valid values when the category
— or a ``disease_name`` filter within it — is not recognised.
- **triage_variant_3d** — Comprehensive clinical triage for a missense variant.

Fuses the upstream signals this tool currently wires into a single
prioritised report:

1. **Pathogenicity** — ClinVar interpretation + review status. The
   ``alphamissense_score`` / ``alphamissense_interpretation`` fields
   are always ``null`` / "Not available" here: AlphaMissense is not
   wired into this tool. For an AlphaMissense pathogenicity score use
   ``generate_variant_clinical_report``.
2. **Population genetics** — gnomAD LOEUF / pLI gene-constraint
   scores. Per-variant allele frequencies and the per-ancestry
   breakdown are not wired into this tool.
3. **Disease associations** — a placeholder note pointing at
   ``get_target_diseases()``; the Open Targets / MONDO traversal is
   a roadmap (Wave-3) item.
4. **Structural context** — a text note pointing at
   ``analyze_structural_confidence`` (resolve the gene to a UniProt
   accession first); the AlphaFold pLDDT / PAE join into this report
   is a roadmap (Wave-3) item.

Returns a ``pathogenicity_tier``: HIGH / MEDIUM / LOW / UNKNOWN
(derived from ClinVar; the AlphaMissense input is always absent here).

Example: ``triage_variant_3d(hgvs='BRCA1:c.181T>G')``
- **phenotype_to_structures** — Map a clinical phenotype to the protein structures of its disease targets.

Pipeline:
1. Resolve HPO term → associated diseases
2. For each disease → top protein targets (Open Targets)
3. For each target → UniProt ID (for AlphaFold retrieval)

Use the returned UniProt IDs with ``analyze_structural_confidence``
to retrieve AlphaFold structural confidence (pLDDT/PAE).

Example: ``phenotype_to_structures(hpo_id='HP:0002621')``
maps Atherosclerosis → disease targets → UniProt IDs.
- **get_orphan_disease_atlas** — Map an Orphanet rare disease to its MONDO record, HPO phenotypes, and protein targets.

Rare / orphan diseases are often under-studied because their small
patient populations make large trials impractical.  This tool aggregates
the available structural and clinical intelligence into one report to
accelerate research.

Returns:
- MONDO record with ICD-10 coding
- HPO phenotype profile of the disease
- Open Targets protein target evidence scores
- UniProt IDs for AlphaFold structural retrieval

Example: ``get_orphan_disease_atlas(orphanet_id='79318')``
returns the Gaucher disease atlas.
- **compare_disease_target_overlap** — Compare the protein target landscapes of two diseases.

Identifies shared and unique targets between two diseases —
a key analysis for drug repurposing, identifying shared mechanisms,
and understanding comorbidity.

Returns:
- Shared targets (present in both disease target sets)
- Unique to Disease A / Disease B
- Jaccard similarity score of target sets

Example: ``compare_disease_target_overlap(
    mondo_id_a='MONDO:0004975',  # Alzheimer disease
    mondo_id_b='MONDO:0005180',  # Parkinson disease
)``
- **resolve_icd10_to_mondo** — Resolve an ICD-10 clinical code to MONDO disease ontology terms.

Enables integration between clinical / EHR data (which uses ICD-10)
and the research-grade MONDO ontology used by Open Targets, HPO, and
this MCP.

Example: ``resolve_icd10_to_mondo(icd10_code='I21.0')``
maps ST-elevation MI (ICD-10) to MONDO coronary disease terms.
- **query_variant_database** — Search the local knowledge graph for stored variants.

Returns variants matching the filter criteria. No upstream API calls are
made — all data is served from the local SQLite knowledge graph, which is
populated by the curated boot seed and by any explicit writes through the
knowledge-graph storage API (the analysis tools do not write to it on their
own).
- **query_protein_database** — Recall proteins already stored in the local knowledge graph.

This is a local-recall query, not a live lookup: it returns only proteins that
have previously been written to the local SQLite store (the curated boot seed,
plus anything added through the knowledge-graph storage API). No upstream API is
called. To assess a protein that may not be stored yet, use
``assess_target_druggability`` (druggability tier) or
``analyze_structural_confidence`` (pLDDT), which query live sources.

Filters are combined with AND; omit a filter to leave that dimension
unconstrained. Returns a JSON record with the applied ``query``, a
``result_count``, and the matching ``proteins`` rows. The list is empty when
nothing stored matches — common when only the boot seed is loaded, so a broad
filter returning few rows usually means the store is small, not that no such
protein exists.
- **get_knowledge_graph_stats** — Return statistics about the local knowledge graph.

Shows entity counts, database size, and last activity — useful for
understanding the current contents and coverage of the local store.
- **export_research_dataset** — Export the stored knowledge-graph data for downstream analysis.

Returns all stored entities as JSON-serialisable dicts, suitable for:
- Loading into pandas DataFrames for ML feature engineering
- Importing into R or Julia for statistical analysis
- Feeding into downstream bioinformatics pipelines

Example (Python)::

    import pandas as pd
    result = await export_research_dataset(ExportInput(tables=["variants"]))
    df = pd.DataFrame(result["data"]["variants"])
    high_tier = df[df["clinical_tier"] == "HIGH"]
- **find_drug_gene_network** — Traverse the local knowledge graph from a seed entity.

Given a seed (UniProt ID, gene symbol, or MONDO disease ID), expands its
immediate neighbourhood in the stored drug-gene-disease graph: a gene
symbol resolves to its encoded proteins and reported variants, a UniProt
accession resolves to its stored protein record, and a MONDO disease
resolves to drugs with an indication for it. The store is populated by the
curated boot seed and by explicit writes through the storage API.
- **generate_variant_clinical_report** — Generate a multi-source variant interpretation report.

Cross-references evidence from up to seven upstream databases for a
single HGVS variant into one structured report. The report is a
*research aid*: it surfaces the upstream evidence and the
ACMG/AMP criteria that the available evidence supports, but it is
not a clinical interpretation and must not be used as a diagnostic
without independent review by a qualified clinical laboratory.

1. **Ensembl VEP** — functional consequence, SIFT/PolyPhen/CADD predictions
2. **ClinVar** — clinical pathogenicity classifications and review status
3. **gnomAD v4** — population allele frequencies (gnomAD v4, ~807k individuals)
4. **AlphaMissense** — deep-learning missense pathogenicity (Cheng et al. 2023)
5. **Open Targets** — disease-gene evidence scores
6. **DisGeNET** — curated gene-disease association scores
7. **ChEMBL** — approved drugs acting on the gene product

The report includes a draft ACMG/AMP criteria checklist with evidence
mapping, a structural impact summary, and an actionability statement.
- **assess_target_druggability** — Comprehensive druggability assessment for a protein target.

Integrates four independent druggability signals into a HOT/WARM/COLD/NOT_DRUGGABLE
classification:

1. **Drug precedent** — ChEMBL approved drugs + clinical compounds
2. **Tractability** — Open Targets tractability labels (small-molecule, antibody, PROTAC)
3. **Structural confidence** — AF2 pLDDT (ordered → analysable binding pockets)
4. **Population constraint** — gnomAD LOEUF (highly constrained → safety risk on inhibition)

It assembles existing public-database evidence into one tier; it does
not add scientific judgement and is not a validated predictive model.
- **synthesize_protein_dossier** — Generate a complete protein intelligence dossier from 7 data sources.

It assembles disease associations, drug precedent, population
constraint, ClinVar variants, and cross-species orthologs for one
protein into a single structured record. It composes upstream
databases; it does not add scientific judgement.
- **map_disease_drug_landscape** — Map the complete therapeutic landscape for a disease.

Returns approved drugs, pipeline agents, top druggable targets,
and an investability summary for a given MONDO disease.

Combines Open Targets evidence with ChEMBL drug indications and
MONDO disease hierarchy to produce a comprehensive landscape report
used in business development, competitive intelligence, and
R&D portfolio decisions.
- **classify_variant_acmg** — Generate a draft ACMG/AMP variant classification framework.

Populates ACMG/AMP 2015 criteria (Richards et al.) automatically from
computational evidence.  Designed to pre-populate variant interpretation
forms for clinical laboratory review — NOT a substitute for expert review.
- **find_drug_repurposing_candidates** — Rank existing clinical-stage drugs as repurposing candidates for a disease.

Surfaces approved or trial-stage drugs whose target carries genetic/association
evidence for the disease — i.e. drug-repurposing hypotheses. For the full
approved-plus-pipeline drug picture of a disease (not only repurposing
candidates), use ``map_disease_drug_landscape`` instead.

How it works: take the top ``target_limit`` Open Targets evidence-scored targets
for the disease; for each, fetch its ChEMBL drugs at or above ``min_phase``; drop
duplicate molecules; rank by
``composite_repurposing_score = OT evidence score × (max ChEMBL phase / 4)``.
Ranking uses clinical and association evidence only — no protein structure.

Returns a JSON record whose ``candidates`` list holds up to 20 drugs (each with
ChEMBL ID, name, max phase, target gene/UniProt, OT evidence score, composite
score, and mechanism), plus the candidate count and the methodology string.
Returns an empty ``candidates`` list with a ``message`` when the disease has no
Open Targets associations. The composite score is a prioritisation aid, not an
efficacy prediction — validate mechanistically before acting on it.
- **analyze_structural_confidence** — Analyze AlphaFold structural confidence using pLDDT and PAE.

Returns a structural reliability summary (not a per-residue profile):
- **pLDDT**: the model's mean confidence (AlphaFold DB ``globalMetricValue``)
  plus a coarse confidence tier
- **PAE** (predicted aligned error): mean and max inter-residue uncertainty
  and PAE-derived domain boundaries
- **Druggability pre-screen**: an ordered-fraction estimate and a
  structure-based-drug-design suitability flag
- **compute_topology_fingerprint** — Compute a rotation-invariant topological fingerprint of a protein's fold.

Fetches the AlphaFold model for ``uniprot_id`` and runs persistent homology
(a Vietoris-Rips filtration over the Cα point cloud) to produce a
64-dimensional fingerprint vector plus Betti numbers β₀, β₁, β₂. Use it as the
per-protein input to structure-similarity comparisons:
``compare_proteins_topologically`` and ``find_evolutionary_structural_shifts``
consume these fingerprints.

The Betti numbers summarise fold topology: β₀ counts connected components
(single- vs multi-domain or fragmented chains), β₁ counts loops/holes
(β-barrels, large macrocycles), β₂ counts enclosed voids (cavities). Because
they are invariant to rotation and translation, two orientations of the same
fold produce the same fingerprint.

Returns the fingerprint vector, the Betti numbers, the residue count, and which
method ran. Full persistent homology needs the optional ``[tda]`` extra
(``gudhi``); without it a coarse fallback runs that does NOT compute persistent
homology, and the result flags this. Returns a no-structure result when
AlphaFold DB has no model for the accession. This is a coarse, geometry-only
summary — not a substitute for sequence alignment, RMSD, or functional-homology
assessment.
- **compare_proteins_topologically** — Compare multiple proteins using a TDA-fingerprint distance.

Computes a pairwise distance matrix between the TDA fingerprints of
the provided proteins.  Distance metric: L2 distance between
length-normalised 64-dimensional fingerprint vectors (see
``_fingerprint_distance``).  Distance = 0 means identical
fingerprints; larger values mean more divergent fingerprints.  This
is **not** a Wasserstein distance between persistence diagrams.

Applications:
Possible uses (all of which require independent validation
before any downstream use):

- Drug-repurposing triage: proteins with low fingerprint distance
  may share gross topology.
- Off-target screening: family members with near-zero distance.
- Cross-species comparison of the same gene's structure.

None of these are direct functional or sequence-similarity
measures.
- **find_evolutionary_structural_shifts** — Quantify cross-species structural and sequence divergence for a gene.

For each ortholog, attempts to fetch the AlphaFold structure and compute
a TDA fingerprint distance against the human structure. When an ortholog
structure is available in AlphaFold DB, the ``divergence_method`` is
``tda_fingerprint`` and the distance is the L2 distance between
length-normalised fingerprint vectors. When the ortholog has no
AlphaFold model, the method falls back to ``sequence_identity``
(``1 - identity/100``).

AlphaFold DB coverage of non-human proteomes is partial: model organisms
(mouse, rat, zebrafish) are well-covered; others may not be. The
``divergence_method`` field on each result tells you which method was
used.
- **score_binding_pocket_geometry** — Identify and score putative binding pockets from AlphaFold geometry.

Detects pockets with a geometry-only heuristic. Residues in the
inner 60 percent of the structure by distance from the centroid are
taken as the pocket-forming core, then grown greedily into clusters
within an 8 Angstrom radius. A cluster is kept as a putative pocket
when it has at least ``min_pocket_residues`` members and a mean pLDDT
of at least 50.

Each pocket reports a radius of gyration (compactness of the pocket
residues), a centroid offset (distance of the pocket centroid from
the structure centroid; larger means more peripheral — a
solvent-accessible cleft rather than a dead-central cavity, and NOT a
measure of solvent burial), a mean pLDDT, and a druggability index.
The druggability index runs 0 to 100 and is the sum of four equally
weighted 0 to 25 sub-scores: residue count, radius of gyration, mean
pLDDT, and centroid offset.

This is a fast, dependency-free pre-screen, not a substitute for a
validated pocket detector such as fpocket or P2Rank. It needs no ML
model, is fully reproducible from AlphaFold coordinates, and runs in
air-gapped deployments.
- **detect_intrinsically_disordered** — Map intrinsically disordered regions (IDRs) using pLDDT as proxy.

IDRs with pLDDT < 50 are predicted to be disordered in isolation by AlphaFold.
This pLDDT-as-disorder-proxy approach is consistent with Ruff & Pappu (2021)
and scales to the full human proteome from precomputed AlphaFold confidence.

IDR functional categories returned:
- **Linkers**: short (< 20 aa) disordered regions between domains
- **Tails**: N/C terminal IDRs
- **Long IDRs**: candidate intrinsically disordered protein (IDP) segments

Clinical relevance:
- IDRs are enriched for disease-causing mutations
- IDRs host post-translational modification sites (phosphorylation, ubiquitination)
- Long IDRs are emerging drug targets (targeted covalent inhibitors, phase separation modulators)
- **get_protein_structure** — Retrieve a protein's AlphaFold model: metadata, download URLs, optional coordinates.

The single entry point for getting the predicted structure itself. Returns the
AlphaFold DB entry metadata — entry ID, model version and creation date,
organism, gene, UniProt description, the amino-acid sequence and its length, and
the model's mean pLDDT — plus stable download URLs for the PDB and mmCIF
coordinate files, the PAE matrix and image, and the AlphaMissense substitutions
CSV. Set ``include_coordinates`` to embed the full PDB coordinate text directly.

Use the sibling structure tools for *interpretation* rather than retrieval, so
their scopes don't overlap: ``analyze_structural_confidence`` for a pLDDT/PAE
confidence read, ``score_binding_pocket_geometry`` for pockets,
``compute_topology_fingerprint`` for fold topology, and
``detect_intrinsically_disordered`` for disorder. This tool hands you the
structure and its handles; it does not score or interpret the model.

Returns ``structure_available: false`` with an explanatory note when AlphaFold DB
has no model for the accession — an expected coverage gap, not a server fault.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "alphafold-sovereign-mcp": {
    "command": "uvx",
    "args": ["alphafold-sovereign-mcp"]
  }
}
```

## Documentation

## What smaniches/alphafold-sovereign-mcp MCP server does

The smaniches/alphafold-sovereign-mcp MCP server exposes biomedical research workflows through MCP tools. It connects AlphaFold DB with MONDO, HPO, Open Targets, ClinVar, gnomAD, DisGeNET, ChEMBL, and Ensembl. The resulting tools cover disease and phenotype lookup, gene phenotype profiles, drug-target relationships, variant triage, protein structures, and cross-species comparisons.

Several tools combine results from multiple sources. Examples include generating a draft variant report from an HGVS expression, mapping phenotypes to structures and targets, assembling a protein dossier, ranking drug-repurposing candidates, and mapping a disease to approved and pipeline drugs. Local tools can query stored variant or protein assessments, traverse drug-gene-disease relationships, report graph statistics, and export tables as JSON.

## How it works

The smaniches/alphafold-sovereign-mcp MCP server is a Python process that communicates with an MCP client. In its normal online mode, individual tools make requests to public upstream services and reconcile their responses. The project describes these operations as orchestration rather than independent scientific judgment.

A SQLite knowledge graph is included for local entities, relationships, queries, traversal, and exports. When the database is empty, a curated seed is loaded with 16 entities and 15 relationships unless seeding is disabled. Analysis calls do not automatically persist every result; data must be written through the knowledge-graph API.

Structural analysis includes pLDDT confidence summaries, PAE-derived domain boundaries, geometric pocket scoring, intrinsic-disorder maps, and optional persistent-homology calculations over C-alpha coordinates. The topology comparator uses length-normalized 64-dimensional fingerprints and L2 distance, so it is not an RMSD, sequence-similarity, or functional-equivalence calculation.

## Setup and configuration

Install the published package with pip, or run it without a permanent installation:

```bash
uvx alphafold-sovereign-mcp
```

Source installation uses `uv pip install -e .`. The optional `tda` extra adds the `gudhi` dependency for full persistent-homology features. The project targets Python 3.10 through 3.13 and MCP specification 2025-06-18.

Set `ALPHAFOLD_OFFLINE=1` to prevent outbound requests before a socket is opened. In that mode, local knowledge-graph tools continue to use local data, while upstream-backed tools report that their sources are unavailable. The default online mode sends identifiers to the relevant public upstreams. DisGeNET requires a separate free API key. `AFSMCP_DISABLE_KG_SEED=1` disables automatic loading of the initial graph seed.

## Tools and capabilities

Available capability groups include:

- Search MONDO diseases, resolve ICD-10 codes, inspect HPO terms, and build gene phenotype profiles.
- Find disease targets, target-associated diseases, target overlap, drug landscapes, repurposing candidates, and drug-gene network paths.
- Cross-reference HGVS variants with ClinVar and gnomAD, create draft ACMG/AMP checklists, and query locally stored triage results.
- Retrieve AlphaFold model metadata, download links, and optional coordinates; assess confidence, disorder, pockets, topology, and evolutionary structural shifts.
- Assess heuristic target druggability, synthesize protein dossiers, inspect local graph statistics, and export research data as JSON.

## Limitations and notes

The smaniches/alphafold-sovereign-mcp MCP server is beta software and has engineering validation but no independent scientific validation or production deployment described in the provided material. It is not a hosted service, does not train AlphaFold models, and is not certified for regulated use. Generated ACMG/AMP criteria are draft evidence surfaces, not clinical-laboratory review. Druggability tiers are heuristic. AlphaFold inputs are predicted structures with per-residue confidence, so low-pLDDT regions require caution. The project is licensed under Apache-2.0 and is not affiliated with Google DeepMind or EMBL-EBI.

_Full upstream README: https://allmcps.com/mcp/smaniches-alphafold-sovereign-mcp/readme_