Openpgx

🧬 OpenPGx — The Open Standard for AI-Readable Pharmacogenomics

OpenPGx is an open, AI-readable standard for pharmacogenomic data. It defines how genetic variants, drug responses, disease risks, and traits should be structured so that any AI system can understand and reason about them.

The standard is delivered today through an MCP Server — plug it into Claude, Cursor, or any MCP-compatible AI and start asking questions about your DNA.

"Can I take Ozempic?"       → Checks GLP1R variants against your genotype
"How about Vyvanse?"        → Cross-references CYP2D6 + COMT studies
"What's my Alzheimer risk?" → 19 disease conditions analyzed with odds ratios

🔒 Privacy-first: your data never leaves your computer. No cloud, no account, no tracking.

openpgx.ai · GitHub · npm

📋 Table of Contents

• ✨ Why OpenPGx?
• 🚀 Install in 30 Seconds
• 💬 What Can You Ask?
• 🧠 Knowledge Base
• 🛠️ MCP Tools
• 🤝 Contributing Studies
• 📤 Output Standard (v0.4.0)
• 🏗️ Architecture
• 🧪 Development
• 🔒 Privacy & Security
• 📄 License
• ⚠️ Disclaimer

✨ Why OpenPGx?

Pharmacogenomic data is trapped in formats that AI can't use. FHIR is verbose and hospital-centric. PharmCAT is great but not designed for AI consumption. Research papers are unstructured text.

OpenPGx is different:

• 🤖 AI-readable — structured JSON that any LLM can parse and reason about
• 📚 Study-driven — every interpretation traces back to a published study with PMID/DOI
• 🌍 Open source — add a study by dropping a JSON file and opening a PR
• 🔗 FHIR-compatible — not a replacement, but an intelligence layer that exports to FHIR resources

📄 The OpenPGx Study Format

One JSON file = one gene-drug study. This is the atomic unit of pharmacogenomic knowledge in OpenPGx:

{
  "gene": "ALDH2",
  "category": "drug_metabolism",
  "gene_description": "Alcohol metabolism, nitroglycerin bioactivation",
  "drugs": ["nitroglycerin", "ethanol"],
  "source": {
    "pmid": "16395407",
    "doi": "10.1172/JCI26564",
    "source_type": "pubmed",
    "title": "ALDH2 Glu504Lys polymorphism and nitroglycerin efficacy",
    "journal": "Journal of Clinical Investigation",
    "year": 2006,
    "cohort_size": 986,
    "url": "https://pubmed.ncbi.nlm.nih.gov/16395407/",
    "finding": "ALDH2*2 carriers show reduced nitroglycerin bioactivation."
  },
  "snps": [
    {
      "rsid": "rs671",
      "risk_allele": "A",
      "reference_allele": "G",
      "interpretations": {
        "AA": { "phenotype": "ALDH2 Deficient", "effect": "Nitroglycerin ineffective", "severity": "severe" },
        "AG": { "phenotype": "Reduced Activity", "effect": "33-40% less efficacy", "severity": "moderate" },
        "GG": { "phenotype": "Normal", "effect": "Standard response", "severity": "info" }
      }
    }
  ],
  "evidence_level": "established"
}

💡 Want to contribute a new drug-gene study? Create a file like this in data/pgx/studies/ and open a PR. No code changes needed.

🚀 Install in 30 Seconds

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "openpgx": {
      "command": "npx",
      "args": ["-y", "openpgx"]
    }
  }
}

Restart Claude Desktop. Done. ✅

Claude Code (CLI)

claude mcp add openpgx -- npx -y openpgx

Cursor

Open Settings > MCP > Add new MCP Server:

{
  "mcpServers": {
    "openpgx": {
      "command": "npx",
      "args": ["-y", "openpgx"]
    }
  }
}

Windsurf / Cline / Any MCP Client

Same configuration. OpenPGx uses stdio transport — any MCP-compatible client works:

npx openpgx

☁️ Remote Server (No Install)

Don't want to install anything? Use the hosted server directly:

{
  "mcpServers": {
    "openpgx": {
      "type": "streamable-http",
      "url": "https://mcp.openpgx.ai/mcp"
    }
  }
}

This connects to our remote MCP server via Streamable HTTP — same 9 tools, zero local setup. Your genome is parsed server-side and stored temporarily in memory (30-minute session TTL).

⚠️ Privacy note: For maximum privacy, prefer the npx install — everything stays on your machine. The remote server processes your data but does not store it permanently.

💬 What Can You Ask?

💊 Medications (Pharmacogenomics)

"Upload my genome"                    → parse your raw DNA file
"Can I take Ozempic?"                 → check semaglutide + GLP1R
"What about Venvanse?"                → brand names work (60+ brands mapped)
"Is modafinil right for me?"          → checks COMT + CYP2C19 interactions
"Compare sertraline vs escitalopram"  → head-to-head comparison
"Weight loss medications"             → search by category
"antidepressivo"                      → Portuguese works too
"ozmpic"                              → typos are auto-corrected

🏥 Disease Risks

"What's my cancer risk?"              → check specific conditions
"Full risk report"                    → all 19 conditions analyzed
"Do I have the Alzheimer gene?"       → APOE status
"Am I at risk for blood clots?"       → Factor V Leiden check

🧬 Traits

"Trait report"                        → all 25+ traits
"Am I lactose intolerant?"            → lactose persistence check
"Am I a morning person?"              → chronotype analysis

🌿 Supplements

"Supplement protocol"                 → MTHFR, COMT, VDR, BCMO1, FUT2, CBS
"Should I take methylfolate?"         → based on your MTHFR status

🧠 Knowledge Base

All backed by published research with PMID/DOI.

🧬 Genes with Study Data (109)

Every gene is backed by at least one published study with interpretations per genotype. The authoritative list is the set of gene fields in data/pgx/studies/*.json; the table below groups major clinical themes (some genes appear in more than one theme in the data).

💊 127 Medications & Compounds

🏥 19 Disease Risk Conditions

🎯 31 Traits

Caffeine metabolism, alcohol flush, lactose tolerance, muscle composition, chronotype, eye color, and more.

🩺 Clinical Conditions Covered by Gene Studies

Beyond disease risk SNPs, the gene studies provide pharmacogenomic guidance across these clinical areas:

🛠️ 9 MCP Tools

🤝 Contributing Studies

OpenPGx is designed for open source contribution. Adding a new drug-gene study requires zero code changes — just a JSON file.

📝 How to Contribute

1. 🔍 Find a pharmacogenomic study (PubMed, CPIC guidelines, PharmGKB)
2. 📄 Create a JSON file in data/pgx/studies/ following the naming pattern: {gene}_{year}_{slug}.json
3. 🚀 Open a PR

The system automatically:

• ✅ Creates the gene if it doesn't exist in the catalog
• ✅ Registers all rsIDs for DNA parsing
• ✅ Builds the drug-to-gene index
• ✅ Makes the interpretations available in all reports

📋 Study File Template

{
  "gene": "GENE_SYMBOL",
  "category": "drug_metabolism",
  "gene_description": "What this gene does",
  "drugs": ["generic_drug_name"],
  "source": {
    "pmid": "12345678",
    "doi": "10.xxxx/xxxxx",
    "source_type": "pubmed",
    "title": "Study title",
    "journal": "Journal name",
    "year": 2024,
    "cohort_size": 1000,
    "url": "https://pubmed.ncbi.nlm.nih.gov/12345678/",
    "finding": "One-line summary of the key finding"
  },
  "snps": [
    {
      "rsid": "rs12345",
      "risk_allele": "A",
      "reference_allele": "G",
      "interpretations": {
        "AA": { "phenotype": "Poor Metabolizer", "effect": "...", "recommendation": "...", "severity": "severe" },
        "AG": { "phenotype": "Intermediate", "effect": "...", "recommendation": "...", "severity": "moderate" },
        "GG": { "phenotype": "Normal", "effect": "...", "recommendation": "...", "severity": "info" }
      }
    }
  ],
  "evidence_level": "established"
}

📖 Full schema: (see $defs/study_contribution)

📤 The OpenPGx Output Standard (v0.4.0)

Patient-facing OpenPGx files are a single JSON object. The only required top-level field is openpgx_version (must be "0.4.0"). Everything else follows .

🏗️ Top-Level Structure

✅ Minimal Valid Skeleton

Only the required field:

{
  "openpgx_version": "0.4.0"
}

📦 Example with Main Optional Sections

Names shortened; see schema for full $defs:

{
  "openpgx_version": "0.4.0",
  "metadata": {
    "generated_at": "2026-04-12T12:00:00Z",
    "generator": "openpgx-mcp/1.x",
    "sources": ["CPIC", "PharmGKB"]
  },
  "patient": {
    "raw_data_source": "23andMe",
    "ancestry": "european"
  },
  "observations": [
    {
      "gene": "CYP2C19",
      "rsid": "rs4244285",
      "genotype": "AG"
    }
  ],
  "medications": [
    {
      "drug": { "name": "clopidogrel", "class": "antiplatelet" },
      "pgx_associations": [
        {
          "gene": "CYP2C19",
          "rsid": "rs4244285",
          "effect": "Reduced active metabolite formation",
          "evidence": { "level": "established", "sources": [] },
          "clinical_recommendation": "Consider alternative antiplatelet per guideline"
        }
      ],
      "parsed_at": "2026-04-12T12:00:00Z",
      "parse_source": "cpic_guideline",
      "confidence": { "score": 0.9, "evidence_level": "established" }
    }
  ],
  "fhir_mapping": {
    "resource_mappings": {
      "observations": "Observation (code: LOINC 81247-9 'Master HL7 genetic variant reporting panel')",
      "medications": "DiagnosticReport (code: LOINC 51969-4 'Genetic analysis report') + MolecularSequence",
      "risks": "RiskAssessment (method: LOINC 75321-0 'Clinical genomics report')",
      "traits": "Observation (category: genomics)"
    }
  }
}

📖 Full schema:

🏗️ Architecture

Raw DNA file (23andMe .txt / Genera .csv)
        |
        v
+------------------+
|  Parser           | --> Extracts relevant SNPs from 600K+ raw data
|  (local, private) |
+------------------+
        |
        v
+------------------+
|  Study Catalog    | --> 118 studies x 109 genes x 219 drugs
|  (data/pgx/       |     Auto-creates gene definitions
|   studies/*.json)  |     Builds drug-gene index at runtime
+------------------+
        |
        v
+------------------+
|  MCP Tools        | --> 9 tools for AI interaction
|  (server-core.ts) |     Falls back to AI web search when needed
+------------------+
        |
        v
    AI Assistant (Claude, Cursor, ChatGPT, etc.)

🔒 All processing happens locally. No data is sent to any server.

📂 Supported Raw Data Formats

🔎 Smart Drug Resolution

OpenPGx resolves drug names through 6 layers:

🧪 Development

git clone https://github.com/open-pgx/open-pgx.git
cd open-pgx/mcp-server
npm install
npm run build
npm start

📁 Project Structure

mcp-server/
├── src/
│   ├── index.ts            # Entry point (stdio transport)
│   ├── server-core.ts      # MCP tools (11 tools)
│   ├── pgx-catalog.ts      # Study loader, gene index, phenotype inference
│   ├── parsers.ts           # 23andMe & Genera raw data parsers
│   ├── pharmacogenes.ts     # Barrel re-exports
│   ├── drug-resolver.ts     # 6-layer smart drug resolution
│   ├── risk-catalog.ts      # Disease risk definitions
│   ├── trait-catalog.ts     # Trait definitions
│   └── types.ts             # Shared TypeScript interfaces
├── data/
│   ├── pgx/studies/         # 118 study files (the knowledge base)
│   ├── risks/               # Disease risk condition definitions
│   ├── traits/              # Trait definitions
│   ├── drugs_embeddings.json # TF-IDF vectors for semantic search
│   └── tfidf_vocab.json     # TF-IDF vocabulary
├── genomes/                  # Safe gitignored dir for your DNA files
└── package.json

🔒 Privacy & Security

• 🔐 Your genetic data never leaves your computer
• 🚫 No cloud upload, no account, no tracking
• 🪝 Pre-commit hook prevents accidentally committing DNA files
• 🙈 .gitignore blocks all genetic file patterns
• 🔍 The code is open source — audit it yourself

📄 License

⚠️ Disclaimer

OpenPGx is for educational and research purposes only. It does not replace professional medical advice. Always consult your physician before making decisions about medications or supplements. Genetic risk is probabilistic, not deterministic. Evidence levels and source publications are provided for every association.

🧬 OpenPGx — The open standard for AI-readable pharmacogenomics.

openpgx.ai · GitHub · npm