AlphaFold Sovereign MCP

Answering a structural-biology or variant question usually means querying
many public databases by hand — AlphaFold DB, Open Targets, ClinVar,
gnomAD, and more — and reconciling their formats. This server wraps those
sources behind one set of MCP tool calls that run as a local process on
your own machine, with no hosted service of ours in the path, no
telemetry, and a local SQLite knowledge graph that never leaves your disk.
In the default online mode the tools query those public upstreams
directly, so the identifiers you look up are sent to them (and one,
DisGeNET, needs its own free API key); set ALPHAFOLD_OFFLINE=1 to refuse
outbound requests before any socket opens, so no identifier leaves the
machine (the knowledge-graph tools still answer from local data; the
upstream tools report their source as unavailable). "Sovereign" here means
local-first — your compute and stored results stay on your machine — not
that the server runs without a network.

A Model Context Protocol server — an AlphaFold MCP server — that
wraps AlphaFold DB and 8 other public biomedical data sources behind
a set of MCP tool calls, with a conditional UniProtKB request to verify
explicitly requested displayed isoforms. It is backed by a local SQLite
knowledge graph with query and export tools (results can be persisted through its API;
automatic per-invocation persistence is not yet wired).

This is an unfunded, independent open-source project. It is not a
service, not certified for any regulated use, and its outputs are
research aids that should be reviewed by qualified humans before any
clinical or regulatory use.

Research authorship: Santiago Maniches (ORCID 0009-0005-6480-1987) independently directs and maintains this server and is the sole scientific author of its original research contributions. AI-assisted tools have supported coding, testing, and internal review. They are not scientific coauthors, clinical validators, or a substitute for independent evaluation. The public databases, prediction models, and existing algorithms remain credited to their sources.

This project is not affiliated with, endorsed by, or sponsored by
Google DeepMind or EMBL-EBI. "AlphaFold" is a trademark of its
respective owner and is used here only to describe the public data
(the AlphaFold DB API) that this software consumes.

Status: Beta. Engineering-validated (100% line and branch
coverage). Not yet scientifically validated by
independent domain experts; not yet deployed in production. See
STATUS.md and LIMITATIONS.md.

What the evidence does and does not establish

Predicted structure is not an observed structure. AlphaFold predicts a
protein's three-dimensional structure from sequence and learned structural
relationships. Its coordinates represent a model of a possible conformation,
not a direct observation or a guarantee that a protein adopts that single
conformation in every biological context. Proteins are dynamic; binding
partners, environment, sequence changes, alternative conformational states,
and disorder can matter. pLDDT and PAE characterize aspects of prediction
uncertainty. They are not experimental validation probabilities and do not
measure how often the protein adopts a conformation in a cell.

Experimental structure evidence is different. A PDB entry may record an
experimentally determined structural model, with its own experimental
conditions, modeled residues, missing or disordered regions, uncertainty,
and quality measures. It is not a universal photograph of all conformations.
PDBe/SIFTS provides sequence-to-structure coordinate correspondences;
correct correspondence requires matching the exact UniProt accession and
position, PDB entry, molecular entity, chain identifiers, sequence positions,
author numbering and insertion codes as applicable. A verified coordinate
correspondence is not independent validation of an AlphaFold prediction
or proof of a specific biological mechanism.

Automated annotations are a third evidence class. The optional PDBe/IUCr
client retrieves AI-text-mined publication mentions and source-reported
residue correspondences. Multiple rows, chains or PDB entries derived from
the same paper are not independent replications. An extraction score is not
a scientific confidence measure. A paper reporting one tested substitution
does not substantiate other substitutions or clinical pathogenicity.

This MCP is a source-attributed connector, not a new structure predictor or
experimental/clinical validator. The source-reported identities and
limitations travel with the output. Deterministic parsing and regression
tests can validate the software contract; independent checks of live
coordinate mappings can test a narrow source-consistency claim, but cannot
turn predictions, text-mined mentions, or a coordinate join into biological
ground truth. When a required correspondence cannot be established, the
correct state is unresolved rather than guessed.

See AlphaFold DB compatibility,
scientific limitations, and
validation status.

What this is

A Python MCP server that:

• Wraps AlphaFold DB, MONDO, HPO, Open Targets, ClinVar, gnomAD,
  DisGeNET, ChEMBL, and Ensembl behind MCP tool calls. Explicit numbered
  isoforms may also trigger a UniProtKB sequence-and-identity check. Each call
  preserves upstream records and their provenance. Retrieval is not
  a new biological observation; derived workflows are explicitly identified
  as Topologica calculations rather than source-reported findings.
• Composes upstreams into multi-source workflows: variant
  cross-reference reports, disease–target landscape summaries,
  heuristic target-druggability scoring, drug-repurposing candidate
  ranking, and cross-species structural-distance computation.
• Ships a local SQLite knowledge graph (storage/knowledge_graph.py)
  with query, export, and traversal tools. Fresh installations begin
  without automatically inserted biomedical records; data is stored by
  explicit writes through the knowledge-graph API. Existing SQLite files
  are preserved, including illustrative rows from earlier releases;
  historical numerical values are not independently validated source
  records. Analysis tools do not automatically persist their results.
• Includes an exploratory Cα-derived feature-vector module. With the
  optional [tda] extra (gudhi), it reports H₀/H₁ terminal-filtration
  Betti numbers; H₂ is not computed. The fallback reports a 4-Å contact
  graph component count and geometric features, not persistent homology.
  L2 distance between those feature vectors is not a calibrated measure
  of protein homology or biological function.

It targets mcp-spec 2025-06-18 and is CI-tested on Python 3.11–3.13.
Python 3.10 reached upstream end of life on 1 October 2026 and is no longer
supported. New installs require Python 3.11+. The runtime requires patched
dnspython>=2.9.0 (CVE-2026-114605); optional documentation builds require
pillow>=13.0.0 to avoid the affected Pillow 12 line. Existing Python 3.10
users should upgrade their interpreter before upgrading this package.

AlphaFold DB compatibility: the prediction API announced modern model
and sequence field names and a legacy-field sunset in June 2026.
The sampled live API still exposes old aliases as of 9 October 2026.
The client uses the current fields, retains legacy-response compatibility, and
selects the exact requested UniProt accession when the API returns
multiple isoforms. See the API compatibility notes
for the migration contract, remaining fragment limitations, and the
optional October 2026 PDBe/IUCr literature-annotation evidence client.
Those annotations are upstream PDBe research, not an independent
AlphaFold Sovereign scientific discovery.

Evidence responsibility

AlphaFold Sovereign MCP does not develop or validate AlphaFold's underlying
structure predictions, MONDO ontology assertions, UniProt annotations, or
ClinVar submissions. Those belong to the cited source and retain their
source-reported confidence and limitations.

Topologica is responsible for reliable retrieval, accession identity,
cross-source joins, reproducible local calculations, provenance attribution,
and honest failure/uncertainty reporting. An inference made from a predicted
structure remains conditional on that prediction; it does not become an
experimental observation because it is joined to another database. Derived
heuristics are research aids, not source-validated clinical conclusions.

ClinVar identity boundary: A gene-relative expression such as
BRCA1:c.181T>G discovers possible records but does not identify a unique
reference allele; results are labelled unverified candidates and their
classifications cannot be assigned to that query. A matching versioned
transcript expression such as NM_007294.4:c.181T>G permits only a literal
transcript-title match. ClinVar Variation IDs can represent sets of alleles;
neither match level establishes independent clinical equivalence or a
patient-specific classification. Source failures are reported separately
from absent matches. No cross-transcript equivalence is assumed.

What this is not

• It is not a hosted service or a SaaS.
• It is not certified for any regulated use (HIPAA, GxP, 21 CFR
  Part 11, FedRAMP, FIPS, SOC 2). The code structures audit logging
  in a way that could later support such a certification, but no
  such audit has been performed.
• It does not train, fine-tune, or publish AlphaFold models — it
  consumes AlphaFold DB's public REST API.
• Variant-report evidence is a provisional computational signal for
  expert review, not established ACMG/AMP criteria. The
  classify_variant_acmg tool does not assign a clinical class when
  gene–disease mechanism and criterion-specific evidence are unverified.
• The "druggability tier" that assess_target_druggability returns is
  a heuristic built from drug-precedent counts, Open Targets
  tractability labels, pLDDT, and gnomAD constraint. It is not a
  validated prediction.
• "Structural distance" is an L2 distance on derived Cα feature vectors.
  It is not sequence identity, RMSD, persistence-diagram Wasserstein
  distance, validated homology, or functional equivalence. Methods are
  reported separately rather than sorted on incompatible scales.
• The AlphaFold structures consumed here are predicted models with
  per-residue pLDDT confidence, not experimental structures. Low-pLDDT
  regions are unreliable; some proteins (BRCA1 among them) are largely
  low-confidence, and structural inference over those regions should
  be treated with caution.

For a complete, itemised list of known limitations (with module
references, impact, and planned resolution), see LIMITATIONS.md.
For the high-level posture — what is engineering-validated vs. what is
not yet scientifically validated — see STATUS.md.

Install

From PyPI (recommended)

pip install alphafold-sovereign-mcp

Or run it without installing using uvx:

uvx alphafold-sovereign-mcp

Every release on PyPI is built by the release.yml workflow under
OIDC Trusted Publishing and attached to a signed GitHub Release with
Sigstore (cosign) signature bundles, a CycloneDX SBOM, and a Zenodo
DOI mirror. SLSA L3 build provenance is generated in CI by
slsa-github-generator; attaching the attestation to each release is a
roadmap item. scripts/replicate.sh downloads the exact published wheel
and sdist, recomputes their PyPI SHA-256 digests, verifies the GitHub
Release Sigstore bundles against those bytes and this repository's release
workflow identity, and independently verifies that the released CycloneDX
SBOM is bound to the downloaded wheel. If SLSA provenance is attached to a
future release, the same script verifies it against the wheel when
slsa-verifier is installed.

From source

git clone https://github.com/smaniches/alphafold-sovereign-mcp
cd alphafold-sovereign-mcp
uv pip install -e .
# With persistent-homology TDA (requires gudhi):
# uv pip install -e ".[tda]"

Verify the install

$ alphafold-sovereign --version
1.5.10
$ alphafold-sovereign --self-test
SELF-TEST PASS - ACMG helpers behave as expected on the BRCA1 c.5266dupC fixture.

If you ran it via uvx without installing, use
uvx alphafold-sovereign-mcp --self-test instead (the bare
alphafold-sovereign script is only on PATH after a pip/uv install).

--self-test runs fully offline: it checks the deterministic ACMG-evidence
helpers (VEP, gnomAD, and AlphaMissense mapped to ACMG criteria) against a
built-in BRCA1:c.5266dupC fixture. Returns exit code 0 on PASS, non-zero on
FAIL. No network calls, no credentials required.

Configure Claude Desktop

Add to claude_desktop_config.json:

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

Restart Claude Desktop and the tools become available in conversations.
Try asking, for example: "Triage BRCA1 c.5266dupC" or "Assess EGFR
as a drug target". See examples/ for source-retrieval workflow
guidance. The previous illustrative clinical-session transcripts were retired.

Offline mode

ALPHAFOLD_OFFLINE=1 alphafold-sovereign-mcp

Refuses outbound HTTP before a socket is opened (raising AirGapError), except to hosts you explicitly allowlist via ALPHAFOLD_ALLOW_HOSTS. The knowledge-graph query and export tools still answer from the local SQLite store. The upstream-querying tools have no local cache and report their source as unavailable; note that the structure tools currently surface this as a "no AlphaFold model" result rather than an explicit offline error.

Tool inventory

The server exposes 29 MCP tools across four modules. Each tool's
input schema is a Pydantic model; results are JSON.

Disease & ontology (tools/disease.py)

Precision medicine (tools/precision_medicine.py)

Computational candidate signals are not assessed clinical ACMG/AMP
criteria. Source classifications (for example, ClinVar) retain their
original attribution; clinical interpretation requires independent review.

Structure intelligence (tools/structure_intelligence.py)

Knowledge graph (tools/knowledge_graph_tools.py)

Example usage

See examples/ for research workflow guidance.
The previous named clinical session transcripts were retired because
they described an obsolete output contract. Current synthetic regression
tests exercise retrieval and evidence attribution without asserting
independently validated clinical conclusions.

Clinical variant report

generate_variant_clinical_report(hgvs="BRCA1:c.181T>G")

The server searches ClinVar, gnomAD, AlphaMissense (via AlphaFold DB),
Open Targets disease evidence, ChEMBL and Ensembl VEP, and returns a
source-attributed research report with unreviewed computational signals.
The gene-relative example above is a candidate search: it cannot borrow a
ClinVar record's classification as though it proved allele identity. Use a
versioned transcript expression for strict transcript-title matching; even
then, additional validation is required for clinical allele identity. The
client does not automatically perform a variant-specific experimental-
structure or SIFTS mapping.

Optional PDBe/IUCr literature evidence

The clinical-report tool also supports an opt-in, source-attributed
residue-annotation lookup, available only when both a canonical UniProt
accession and its one-based UniProt residue position are provided:

generate_variant_clinical_report(
    hgvs="RBM39:p.Trp495Ala",
    include_literature_evidence=True,
    literature_uniprot_id="Q8VH51",
    literature_uniprot_residue=495,
)

The example demonstrates the request shape, not proof that this HGVS
expression has been transcript-mapped or clinically interpreted.
Returned literature_residue_evidence preserves PDBe/IUCr annotation
provenance: publication identifiers, text-mined sentence and exact span,
extraction confidence, experimental PDB chain/residue information,
and source-reported UniProt correspondence. Source errors and ambiguous
or missing residue mappings are explicitly distinguished.

This evidence does not change ACMG criteria or pathogenicity tiers.
Verify the exact HGVS-to-UniProt coordinate independently; the client does
not independently validate SIFTS or experimental quality. See the
compatibility and mapping limitations.

Drug repurposing

find_drug_repurposing_candidates(disease_mondo_id="MONDO:0007739")

Returns drugs whose Open Targets evidence connects them to the
disease, ranked by a composite of OT evidence score × the maximum
ChEMBL clinical phase reached against the target.

Cross-species structural divergence

find_evolutionary_structural_shifts(
    gene_symbol="ACE2",
    target_species=["mus_musculus", "rhinolophus_ferrumequinum"]
)

For each species: fetches the ortholog (Ensembl), the AlphaFold
structure, computes the TDA fingerprint, and returns the L2 fingerprint
distance from the human structure along with sequence identity.

Data sources

UniProt accessions are used throughout as protein identifiers. The
UniProtKB REST API is queried only for an explicit isoform not separately
labeled in AlphaFold DB: its curated Displayed designation and full canonical
sequence must agree with the model before reuse. This extra upstream
request has its own rate limit and is blocked in offline mode. Failed
verification raises an error rather than proving no model exists.
Domain (InterPro),
Gene Ontology, experimental-structure (RCSB PDB), and tissue-expression
(Human Protein Atlas) lookups are not integrated in this release.

The optional PDBe/IUCr literature client is not a tenth default core
source: it is called only when include_literature_evidence=True and an
explicit UniProt coordinate is supplied. The data originates in PDBe's
IUCr text-mining pipeline and requires its own upstream attribution.
No experimental RCSB PDB structure retrieval is implied.

See NOTICE for full attributions.

Architecture

clients/_base.py
  ├── Air-gap enforcement (refuses sockets when ALPHAFOLD_OFFLINE=1)
  ├── Token-bucket rate limiting (aiolimiter)
  ├── Exponential backoff with jitter (tenacity)
  ├── Circuit breaker (CLOSED / OPEN / HALF_OPEN)
  └── HTTP/2 transport with connection pooling and keep-alive (httpx)

storage/knowledge_graph.py
  ├── SQLite WAL mode (embedded, ACID)
  ├── 6 entity tables: proteins, variants, diseases, drugs, genes, phenotypes
  ├── 4 relationship tables: protein_disease, protein_drug, variant_disease, gene_phenotype
  ├── tool_invocations audit table (SHA-256 of input + output, timestamps)
  └── Analytical views: variant_summary, drug_landscape

domain/disease.py
  └── Pure Python frozen dataclasses (PathogenicityClass, VariantReport, ...)

domain/druggability.py
  └── Pure, I/O-free target-druggability heuristic (named/cited weights and
      cut-offs, plus confidence / data-completeness / borderline reporting)

See ARCHITECTURE.md for the full module map.

Testing & quality

• A comprehensive offline unit-test suite (respx-mocked upstreams,
  including parametrised expansions); the full suite runs hermetically
  in under a minute on a laptop.
• Coverage on the shipped surface (src/alphafold_sovereign/clients,
  domain, storage, server, tools): 100% line + branch,
  every shipped module at 100%.
• Lint: ruff (19 rule families, see [tool.ruff.lint] in
  pyproject.toml). Type checking: mypy --strict on the full source tree.
• Security: bandit plus CodeQL security-extended.
• Supply chain: release CI builds and attests the distributions, generates a
  wheel-bound CycloneDX SBOM from the installed runtime dependency closure,
  and signs release artifacts with Sigstore. scripts/replicate.sh
  independently downloads the published wheel and sdist, verifies their PyPI
  hashes and Sigstore bundles, and checks the released CycloneDX binding.
  SLSA provenance is generated in CI; attaching it to each GitHub Release
  remains a roadmap item.

The full CI matrix (Python 3.11, 3.12, 3.13 × Ubuntu, macOS)
runs on every push. The coverage percentage above is the number a
git clone && uv run nox -s cov produces on the current HEAD; if you
find a divergence, please open an issue.

Contributing

DCO sign-off required (git commit -s). No copyright assignment.
Coverage gate: CI enforces 100% line and branch coverage on the shipped surface (nox -s cov).
Full guide: CONTRIBUTING.md.

Related MCP servers by the same author

• uniprot-mcp — Model Context Protocol server for UniProt Swiss-Prot and TrEMBL (pip install uniprot-mcp-server).
• semantic-scholar-mcp — Semantic Scholar MCP server, 200M+ academic papers (pip install s2-mcp-server).

Citation

Machine-readable metadata: CITATION.cff (GitHub
renders a "Cite this repository" button in the sidebar that consumes
this file).

@software{maniches_alphafold_sovereign_mcp,
  author    = {Maniches, Santiago},
  title     = {AlphaFold Sovereign MCP},
  year      = {2026},
  version   = {1.5.10},
  url       = {https://github.com/smaniches/alphafold-sovereign-mcp},
  license   = {Apache-2.0},
  orcid     = {0009-0005-6480-1987},
  doi       = {10.5281/zenodo.20134773}
}

When citing results derived from this software, please also cite the
upstream data sources (AlphaFold DB, UniProtKB when verifying explicit
isoforms, Open Targets, ChEMBL, Ensembl, ClinVar, gnomAD, MONDO,
HPO, DisGeNET) according to their own citation
requirements.

License

Copyright 2024–2026 Santiago Maniches.

Licensed under the Apache License, Version 2.0. See LICENSE.

Trademark policy: see TRADEMARKS.md.