AlphaFold Sovereign MCP

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 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 runs on Python 3.10–3.13.

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.7
$ 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 the examples/ directory for three end-to-end illustrations of what a session looks like.

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.10, 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.7},
  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.

Patent reservation: see PATENTS.md. Trademark policy: see TRADEMARKS.md.