{ "markdown": "# ๐ŸŒฑ plant-genomics-mcp\n\n> **50 tools** for plant-genomics locus lookup over the Model Context Protocol โ€”\n> 28 single-locus + 1 motif lookup + 1 region query + 1 variant annotator + 1 gene-set enrichment + 1 BLAST search + 12 parallel-batch + 5 cross-source synthesis variants.\n> Free, public sources: Ensembl Plants, Phytozome BioMart, UniProtKB,\n> Europe PMC, QuickGO, Planteome, PlantCyc/PMN, g:Profiler, NCBI BLAST,\n> Gramene, JASPAR, KEGG, STRING-DB, ATTED-II, ThaleMine, and BAR (Bio-Analytic Resource for\n> Plant Biology).\n\n[![PyPI](https://img.shields.io/pypi/v/plant-genomics-mcp)](https://pypi.org/project/plant-genomics-mcp/)\n[![CI](https://github.com/musharna/plant-genomics-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/musharna/plant-genomics-mcp/actions/workflows/test.yml)\n[![Docker](https://github.com/musharna/plant-genomics-mcp/actions/workflows/docker.yml/badge.svg)](https://github.com/musharna/plant-genomics-mcp/actions/workflows/docker.yml)\n![Python](https://img.shields.io/badge/python-3.11%2B-blue)\n![License](https://img.shields.io/badge/license-MIT-green)\n[![Glama](https://glama.ai/mcp/servers/musharna/plant-genomics-mcp/badges/score.svg)](https://glama.ai/mcp/servers/musharna/plant-genomics-mcp)\n[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.21636352.svg)](https://doi.org/10.5281/zenodo.21636352)\n\n

\n \"Claude\n

\n\n## ๐Ÿ“ฆ Install\n\n```bash\n# Zero-install โ€” uv fetches and runs it on demand\nclaude mcp add plant-genomics --scope local -- uvx plant-genomics-mcp\n```\n\n
\nOther install paths (pipx, Docker, from source)\n\n```bash\n# pipx โ€” installs the CLI onto your PATH\npipx install plant-genomics-mcp\nclaude mcp add plant-genomics --scope local -- plant-genomics-mcp\n\n# GHCR Docker image\ndocker pull ghcr.io/musharna/plant-genomics-mcp:latest\nclaude mcp add plant-genomics --scope local -- \\\n docker run --rm -i ghcr.io/musharna/plant-genomics-mcp:latest\n\n# From source\ngit clone https://github.com/musharna/plant-genomics-mcp.git\ncd plant-genomics-mcp\npython -m venv .venv && .venv/bin/pip install -e .\nclaude mcp add plant-genomics --scope local -- \"$(pwd)/.venv/bin/plant-genomics-mcp\"\n```\n\n
\n\n## ๐Ÿ’ฌ Try it\n\nOnce connected, ask Claude a plain-language question โ€” you don't have to\nname any tool or remember the chain:\n\n> **\"Tell me everything about the Arabidopsis gene AT1G01010 โ€” its\n> function, GO terms, KEGG pathways, protein-interaction partners, and\n> recent papers.\"**\n\nClaude fans out across Ensembl Plants, UniProt, QuickGO, KEGG, STRING-DB,\nand Europe PMC in a single turn and hands back one synthesized answer.\nSwap in any locus and pass `organism=` for cross-species โ€” e.g. rice\n`Os01g0100100` (`oryza_sativa`) โ€” and it routes to the right backends\nautomatically.\n\n## ๐Ÿ› ๏ธ Tools\n\n**50 tools across 23 backends** โ€” Ensembl Plants, Phytozome BioMart,\nUniProtKB, Europe PMC, QuickGO, Planteome, PlantCyc/PMN, g:Profiler,\nAlphaFold DB, PDBe, InterPro, JASPAR, PANTHER, OrthoDB, AraGWAS, 1001 Genomes, NCBI BLAST,\nGramene, KEGG, STRING-DB, ATTED-II, ThaleMine, BAR.\n28 single-locus + 1 motif lookup + 1 region query + 1 variant annotator + 1 gene-set\nenrichment + 1 BLAST search + 12 parallel-batch + 5 cross-source synthesis. Most take a\nTAIR-style locus (e.g. `AT1G01010`) plus\noptional `organism=` (slug / scientific name / common name / NCBI taxid\nโ€” 12-plant curated coverage matrix at the `pgmcp://organisms/coverage`\nMCP resource). All publish JSON `outputSchema`, EDAM ontology tags, and\nbehaviour annotations โ€” every tool is `readOnlyHint` + `openWorldHint`, so\nhosts can surface them without a destructive-action confirmation prompt.\n\n
\nFull tool matrix\n\n| # | Category | Tool | What it does |\n| --- | ----------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| 1 | Gene metadata (live) | `ensembl_plants_lookup_locus` | Fetches gene record from Ensembl Plants REST (any plant species). |\n| 2 | Cross-references (live) | `get_gene_xrefs` | Fetches cross-DB references (UniProt, NCBI Gene, TAIR, GO, โ€ฆ) from Ensembl. |\n| 3 | Gene metadata (live) | `phytozome_lookup_locus` | Fetches gene record from Phytozome BioMart (any Phytozome proteome). |\n| 4 | Protein (live) | `resolve_locus_to_uniprot` | Resolves a locus to its UniProtKB record (Swiss-Prot preferred, TrEMBL OK). |\n| 5 | Literature (live) | `locus_literature` | Searches Europe PMC for papers mentioning the locus (free, no API key). |\n| 6 | GO annotations (live) | `locus_go_annotations` | Fetches QuickGO GO annotations (locus โ†’ UniProt โ†’ QuickGO). |\n| 7 | Sequence search (live) | `blast_sequence` | NCBI BLAST URLAPI โ€” async Put/Get polling with progress notifications. |\n| 8 | Homology (live) | `gramene_homologs` | Fetches Gramene v69 homology entries (ortholog / paralog) with gene_tree_id. |\n| 9 | Pathways (live) | `kegg_pathways` | Fetches KEGG pathway memberships. 7 organisms: Arabidopsis (`ath:`, native AGI), + rice (`osa:`), maize (`zma:`), soybean (`gmx:`), barley (`hvg:`), poplar (`pop:`), brachypodium (`bdi:`) bridged via Ensembl โ†’ Entrez ID. |\n| 10 | Interactions (live) | `string_interactions` | Fetches STRING-DB first-neighbor interaction partners with per-channel score. |\n| 11 | Coexpression (live) | `atted_coexpression` | Fetches ATTED-II Ath-u.c4-0 top-N coexpression neighbors with z-scores. |\n| 12 | Curator summary (live) | `bar_gene_summary` | Fetches BAR ThaleMine + GAIA-aliases curator summary for an Arabidopsis locus. |\n| 13 | Expression (live) | `bar_efp_expression` | Fetches BAR eFP-Browser expression profile (mean ยฑ SD per tissue) for a locus. |\n| 14 | Interactions (live) | `bar_aiv_interactions` | Fetches BAR AIV interaction partners (Arabidopsis + rice) with confidence + papers. |\n| 15 | Curator summary (live) | `tair_locus_info` | Silent upgrade โ€” alias of `bar_gene_summary`. MCP tool name preserved for clients. |\n| 16 | Metabolism (live) | `plantcyc_locus_info` | Walks gene โ†’ enzyme โ†’ reactions โ†’ PlantCyc/PMN pathways (free BioCyc web-services API). The metabolic-pathway view KEGG/GO lack; found=false for non-enzymatic genes. 11 species have a PGDB. |\n| 17 | Sequence (live) | `get_sequence` | Fetches a locus's sequence (genomic / cds / cdna / protein) from Ensembl `/sequence/id` โ€” the fetch half of lookup โ†’ fetch โ†’ BLAST; feed `sequence` to `blast_sequence`. |\n| 18 | Region query (live) | `ensembl_region_query` | Lists gene/transcript/cds/exon features overlapping a genomic interval (chr:start-end) via Ensembl `/overlap/region` โ€” \"what's in this QTL interval\" without a per-locus lookup. |\n| 19 | Enrichment (live) | `go_enrichment` | GO + KEGG over-representation for a gene **list** via g:Profiler g:GOSt โ€” \"what is my DE / co-expression set enriched for?\" Reports unmapped loci; optional custom background. All 12 organisms. |\n| 20 | Plant ontology (live) | `locus_plant_ontology` | Plant Ontology (anatomy / dev-stage) + Trait Ontology annotations for a locus via Planteome (Solr) โ€” the plant-specific ontologies GO doesn't cover. by_ontology rollup; taxon-filtered. Strong for 6 species. |\n| 21 | Structure (live) | `alphafold_structure` | AlphaFold DB predicted 3D model for a locus (locus โ†’ UniProt โ†’ model): global mean pLDDT, per-band confidence, modelled span, and mmCIF / PDB / PAE URLs. found=false when no model is deposited. All 12 organisms. |\n| 22 | Structure (live) | `experimental_structures` | PDBe experimentally-solved (X-ray / cryo-EM / NMR) structures for a locus (locus โ†’ UniProt): best-first PDB id, chain, method, resolution, coverage, residue span. found=false when none deposited (common for plants). All 12 organisms. |\n| 23 | Domains (live) | `interpro_domains` | InterPro domain / family architecture (locus โ†’ UniProt): each entry's accession, name, type, source_database (Pfam included), integrated InterPro id, and residue spans, plus a count_by_type rollup. All 12 organisms. |\n| 24 | TF motifs (live) | `tf_binding_motifs` | JASPAR curated TF DNA-binding profiles for a locus (locus โ†’ UniProt โ†’ symbol search, then UniProt-confirmed): matrix id, TF class/family, assay type (SELEX / ChIP-seq / PBM / DAP-seq), IUPAC consensus, PubMed refs, logo URL. Fuzzy name hits for _other_ genes are quarantined in `name_only_matches`. Arabidopsis-heavy coverage. |\n| 25 | TF motifs (live) | `jaspar_motif` | One JASPAR profile by matrix id (e.g. `MA0570.1`, or `MA0570` for the newest version) including the raw position-frequency matrix โ€” the drill-down companion to `tf_binding_motifs`. |\n| 26 | Interactions (live) | `experimental_interactions` | ThaleMine CURATED EXPERIMENTAL interaction partners (BioGRID / IntAct / PSI-MI) for an Arabidopsis locus โ€” per partner: detection method (two hybrid, pull down, ...), PSI-MI relationship type, physical vs genetic, source DB, PubMed IDs, and an evidence count. The experimental counterpart to `string_interactions` (predicted / text-mined). Arabidopsis only. |\n| 27 | Function (live) | `locus_gene_rifs` | ThaleMine curated GeneRIF statements โ€” one-sentence, manually curated descriptions of what the gene does, each tied to a PubMed ID (HY5 has 114). Citable functional context that GO terms and raw abstracts don't provide. Arabidopsis only. |\n| 28 | Variation (live) | `locus_variants` | Natural (EVA/dbSNP) variants overlapping a locus's genomic span via Ensembl `/overlap/region` โ€” id, source, consequence class, alleles, clinical significance. variant_count + truncated. All 12 organisms. |\n| 29 | Variation (live) | `vep_annotate` | Ensembl VEP consequence prediction for a variant (region + allele, not locus) โ€” most-severe consequence + per-transcript SO terms, IMPACT, SIFT/PolyPhen. All 12 organisms. |\n| 30 | Orthology (live) | `panther_family` | PANTHER protein family + subfamily (id + name), GO terms by aspect, protein class, and pathways. found=false when unclassified. All 12 organisms. |\n| 31 | Orthology (live) | `orthodb_orthologs` | OrthoDB ortholog group (name, evolutionary rate) + cross-species member genes at the Viridiplantae level. organism_count + truncated. All 12 organisms. |\n| 32 | Diversity (live) | `aragwas_associations` | AraGWAS genome-wide association hits per locus โ€” score, MAF, SNP effect, phenotype/study. Arabidopsis-only. |\n| 33 | Diversity (live) | `arabidopsis_natural_variation` | 1001 Genomes natural-variation SNP effects across 1135 accessions โ€” chr, position, effect, impact, amino-acid change, transcript + gene span. Arabidopsis-only. |\n| 34 | Batch (live) | `batch_*` (twelve variants) | Parallel per-locus fanout for tools 1โ€“6, 8โ€“12, 14. Up to 50 loci per call. |\n| 35 | Synthesis (live) | `*_synth` / `consensus_homologs` (four) | Compose 2โ€“5 backends in parallel, return a `SynthesisEnvelope` with per-step status. |\n| 36 | Synthesis (live) | `gene_report` | One-shot \"tell me about this gene\" dossier โ€” annotation + xrefs + protein + domains + GO + KEGG + STRING + literature composed into a rendered Markdown `result.markdown` (+ structured `result.sections`). |\n\n
\n\n## โšก Quickstart\n\nAfter install, the simplest call returns the Ensembl Plants record for\nNAC001 โ€” the canonical worked example used throughout `examples/`:\n\n```jsonc\n// arguments\n{ \"locus\": \"AT1G01010\" }\n\n// result (truncated)\n{\n \"id\": \"AT1G01010\",\n \"organism\": \"arabidopsis_thaliana\",\n \"display_name\": \"NAC001\",\n \"biotype\": \"protein_coding\",\n \"seq_region_name\": \"1\",\n \"start\": 3631,\n \"end\": 5899,\n \"strand\": 1,\n \"assembly_name\": \"TAIR10\",\n \"description\": \"NAC domain containing protein 1 ...\"\n}\n```\n\nCross-species โ€” pass `organism=`:\n\n```jsonc\n{ \"locus\": \"Os01g0100100\", \"organism\": \"oryza_sativa\" }\n```\n\nIn Claude Code, the same prompt fans out across Ensembl, UniProtKB, and\nEurope PMC in a single turn ([animated demo](examples/assets/cc-demo.gif)):\n\n

\n \"Claude\n

\n\nFull per-tool walkthroughs (with real upstream-API transcripts) live in\n[`examples/`](examples/):\n\n| Walkthrough | Coverage |\n| ----------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |\n| [`gene_report_AT1G01010.md`](examples/gene_report_AT1G01010.md) | One-shot Markdown gene dossier โ€” 7 backends composed, with graceful KEGG degradation. |\n| [`analyze_locus_AT1G01010.md`](examples/analyze_locus_AT1G01010.md) | Ensembl โ†’ xrefs โ†’ UniProt โ†’ Europe PMC โ†’ QuickGO chain (5 tools). |\n| [`find_homologs_AT1G01010_NAC_domain.md`](examples/find_homologs_AT1G01010_NAC_domain.md) | BLAST + per-hit UniProt enrichment. |\n| [`biological_context_AT1G01010.md`](examples/biological_context_AT1G01010.md) | Gramene + KEGG + UniProt + STRING + ATTED-II (5 tools). |\n| [`v0.8_synthesis_walkthrough.md`](examples/v0.8_synthesis_walkthrough.md) | All 4 v0.8 synthesis tools (`*_synth` + `consensus_homologs`) on the same locus. |\n| [`cross_organism_walkthrough.md`](examples/cross_organism_walkthrough.md) | v0.9 multi-organism resolver against rice + maize โ€” per-backend routing on PyPI v1.0.4. |\n\n## ๐Ÿ“š Resources & prompts\n\n
\nFour read-only MCP resources + three parameterized prompts\n\nClients discover them via `resources/list` and `prompts/list`.\n\n**Resources** (`resources/read`):\n\n| URI | What |\n| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |\n| `pgmcp://cache/stats` | Per-backend `TTLCache` rollup โ€” `{hits, misses, size}` for each live backend. |\n| `pgmcp://organisms/phytozome` | Slug โ†’ Phytozome `organism_id` map. |\n| `pgmcp://backends/status` | Per-backend liveness rollup โ€” `name`, `base_url`, `kind`, `subscription_gated`. |\n| `pgmcp://organisms/coverage` | Markdown table of all 12 supported plants ร— 9 ID slots (ncbi_taxid / ensembl / phytozome / string / europe_pmc / kegg / atted / gprofiler / plantcyc). |\n\n**Prompts** (`prompts/get`):\n\n| Name | Required | Optional | Chains |\n| -------------------- | ---------- | ------------------------------------------- | ------------------------------------------------------------------------------------ |\n| `analyze_locus` | `locus` | `organism` (default `arabidopsis_thaliana`) | Ensembl โ†’ xrefs โ†’ UniProt โ†’ Europe PMC โ†’ QuickGO. |\n| `find_homologs` | `sequence` | `program` (default `blastp`) | `blast_sequence` โ†’ per-hit `resolve_locus_to_uniprot` for UniProt-shaped accessions. |\n| `biological_context` | `locus` | `top_n` (default 10) | Gramene โ†’ KEGG โ†’ UniProt โ†’ STRING โ†’ ATTED-II. |\n\n
\n\n## ๐Ÿ”Œ Transports\n\n| Transport | How to launch |\n| --------------- | ------------------------------------------------------------------- |\n| stdio (default) | `plant-genomics-mcp` (after install) or via Docker above |\n| streamable-HTTP | `plant-genomics-mcp-http` โ€” POST JSON-RPC at `http://host:port/mcp` |\n\nThe HTTP transport is stateless and emits JSON responses by default โ€”\nthe right shape for registry indexers and remote hosting.\n\n### Hosted endpoint\n\nA small **personal demo** runs at:\n\n```\nhttps://mjarnoldgt76.tail86d19d.ts.net/mcp\n```\n\nIntended for registry indexers, one-off evaluation, and quick\ninteractive testing โ€” **not for production workloads**. No SLA, no\nuptime commitment, URL may change without notice (single laptop on a\nresidential connection).\n\n```bash\n# liveness probe\ncurl https://mjarnoldgt76.tail86d19d.ts.net/healthz\n# {\"status\":\"ok\"}\n\n# connect from Claude Code\nclaude mcp add --transport http plant-genomics-mcp \\\n https://mjarnoldgt76.tail86d19d.ts.net/mcp\n```\n\nFor anything beyond casual evaluation, **self-host**. The HTTP transport\nis the same binary; self-hosting buys deterministic uptime, your own\nbearer-token gate (`PLANT_GENOMICS_MCP_HTTP_TOKEN`), and NCBI BLAST\netiquette under your own contact email.\n\n## โš™๏ธ Configuration\n\nStdio needs no configuration. The two env vars that matter:\n\n| Variable | When | Effect |\n| ------------------------------- | ------------------- | --------------------------------------------------------------------------------------------------------------------- |\n| `PLANT_GENOMICS_MCP_HTTP_TOKEN` | HTTP transport only | Bearer token for `/mcp`; **must be โ‰ฅ32 chars** or the HTTP server aborts at startup. Generate `openssl rand -hex 32`. |\n| `PLANT_GENOMICS_MCP_NCBI_EMAIL` | If you use BLAST | NCBI etiquette contact. Unset โ†’ placeholder + per-call warning; NCBI may throttle. |\n\n
\nAll env vars (HTTP bind, body cap, cache, BLAST concurrency)\n\n| Variable | Default | Effect |\n| -------------------------------------- | ----------------- | ------------------------------------------------------------------ |\n| `PLANT_GENOMICS_MCP_HTTP_HOST` | `127.0.0.1` | HTTP bind address. |\n| `PLANT_GENOMICS_MCP_HTTP_PORT` | `8765` | HTTP TCP port. |\n| `PLANT_GENOMICS_MCP_HTTP_MAX_BODY` | `2097152` (2 MiB) | Reject POSTs with `Content-Length` larger than this. |\n| `PLANT_GENOMICS_MCP_HTTP_STATELESS` | `1` | `0` keeps per-client session state (SSE-style). |\n| `PLANT_GENOMICS_MCP_HTTP_JSON` | `1` | `0` switches the response shape to streaming SSE events. |\n| `PLANT_GENOMICS_MCP_BLAST_CONCURRENCY` | `2` | Max in-flight BLAST searches per process (NCBI per-IP rate limit). |\n| `PLANT_GENOMICS_MCP_CACHE_TTL` | `600` | Per-backend TTL+LRU cache entry lifetime, in seconds. 200-only. |\n| `PLANT_GENOMICS_MCP_CACHE_SIZE` | `256` | Max entries per backend before LRU eviction. |\n| `PLANT_GENOMICS_MCP_CACHE_DISABLED` | unset | Any non-empty value makes every cache a no-op. |\n\nThe cache is process-local โ€” restart the server to drop all entries.\nLong-running calls (retry storms, multi-second Phytozome BioMart POSTs)\nemit MCP `notifications/progress` over the active session; clients opt\nin via `progressToken` in the request `_meta`.\n\n
\n\n## โš ๏ธ Error model\n\n
\nWire-prefix taxonomy + batch result shape\n\nAll live tools raise `PlantGenomicsError` subclasses; the MCP SDK\nstringifies them into the wire `content` with a `[ClassName]` prefix so\nclients can route on failure kind without parsing the message:\n\n| Wire prefix | When |\n| ---------------------------- | ------------------------------------------------------------------ |\n| `[NotFoundError]` | 404 / empty BioMart row / invalid locus identifier |\n| `[RateLimitError]` | 429 retry budget exhausted โ€” back off and retry |\n| `[UpstreamUnavailableError]` | 5xx past retry budget โ€” service outage, try a peer backend |\n| `[PlantGenomicsError]` | Other (BioMart `Query ERROR:` body, unexpected column count, etc.) |\n\nBatch tools return `{tool, count, results, errors}` where\n`results[locus]` is the same shape as the single-locus tool and\n`errors[locus]` is the same `[ClassName] message` string. Ensembl's\nbatch uses the native `POST /lookup/id` endpoint (one HTTP round-trip);\neverything else fans out via `asyncio.gather`.\n\n
\n\n## ๐Ÿงช Development\n\n```bash\n.venv/bin/pip install -e '.[dev]' # or: uv sync --extra dev\n.venv/bin/pytest -q # unit tests\nPLANT_GENOMICS_MCP_LIVE=1 .venv/bin/pytest -q # adds live network probes\nPLANT_GENOMICS_MCP_STDIO_SMOKE=1 .venv/bin/pytest -q # adds stdio smoke\n.venv/bin/ruff check .\n```\n\nWith `uv`, pass `--extra dev` โ€” a bare `uv sync` omits (and removes) the test\ndependencies. See [CONTRIBUTING.md](CONTRIBUTING.md#dev-setup).\n\nCI runs the unit suite + the stdio smoke on every push/PR (matrix:\nPython 3.11, 3.12, 3.13, 3.14 โ€” the full `requires-python` range). The\nlive-network gate is **not** run in CI to avoid flakes from upstream\navailability.\n\n**Scientific validation / drift detection.** `scripts/benchmark_annotations.py`\ndrives a curated corpus of canonical loci (27, spanning all 12 organisms)\nthrough every backend + synthesis pipeline and compares results to a frozen\nbaseline, emitting PASS / DRIFT / FAIL plus cross-source consistency\ninvariants. It's how upstream data drift is caught. A scheduled GitHub Actions\nworkflow (`.github/workflows/benchmark.yml`) runs it weekly and pages on a\nconfirmed regression. Operator guide: [`docs/benchmarking.md`](docs/benchmarking.md).\n\n```bash\n.venv/bin/python scripts/benchmark_annotations.py # full live sweep (~3-5 min)\n```\n\nSee [`CHANGELOG.md`](CHANGELOG.md) for release notes, including the\nv0.8 โ†’ v0.9 `species=`/`organism_id=` โ†’ `organism=` migration and the\nv1.0.1 HTTP-token enforcement change.\n\n## MCP registry\n\nListed in the [official MCP registry](https://registry.modelcontextprotocol.io)\nunder the namespace below (ownership-verification token for `mcp-publisher`):\n\n```\nmcp-name: io.github.musharna/plant-genomics-mcp\n```\n\n## License\n\nMIT โ€” see [`LICENSE`](LICENSE). Underlying services (Ensembl Plants,\nPhytozome, TAIR, PlantCyc, BAR) have their own terms of use; consult\neach before bulk querying.\n", "bytes": 32480, "sha": "76b90e86ea22d30ec6d5a5d39e2da2a3d630aa3cd23e15e2af97a537b67e437a", "repo_slug": "musharna/plant-genomics-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_musharna_plant_genomics_mcp_e100668c/readme" }