Openpgx

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.

---

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:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/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

---

What's in the knowledge base

118 studies · 109 genes · 219 drugs · 19 disease risks · 31 traits — 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).

Category	Genes (representative)
Drug Metabolism	CYP2D6, CYP2C19, CYP2C9, CYP2B6, CYP3A4, CYP3A5, CYP1A2, CYP2E1, ALDH2, BCHE, CES1, FAAH, NAT2, UGT1A1, UGT1A4, UGT1A9, GSTP1, ACE, ADRB1, ADRB2, AGTR1, HMGCR, PCSK9
Drug Targets & Response	VKORC1, DRD2, DRD3, DRD4, HTR1A, HTR2A, HTR2C, GABRA2, GABRA6, GLP1R, GRIK4, SCN1A, SCN9A, MC1R, RYR1, TPMT, NUDT15, DPYD, FKBP5, ESR1, SHBG, COMT, OPRM1, TCF7L2, CLOCK
ADHD / Stimulants	ADRA2A, SLC6A2, SLC6A3, SLC6A4, SNAP25
Drug Transport	SLCO1B1, ABCB1, ABCG2, SLC22A1, SLC22A2
Immune / HLA	HLA-B, HLA-A, HLA-C, HLA-DQB1, IL23R
GLP-1 / Incretin	GLP1R, GIPR, MC4R, PCSK1
Methylation & Vitamins	MTHFR, COMT, VDR, BCMO1, FUT2, CBS, DHCR7, SLC23A1, GC, TCN2, NBPF3
Lipid Metabolism	PNPLA3, TM6SF2, APOE, APOA5, APOB, LDLR, LIPC, LPL, SORT1, PPARG
Energy Balance / Obesity	FTO, MC4R, GHSR, BDNF, PCSK1, TMEM18, FABP2, LYPLAL1
Glucose / Insulin	GCKR, SLC2A2, PPM1K, MTNR1B, IL6, C11ORF65
Circadian Rhythm	PER2, CRY2, NR1D1, CLOCK
Coagulation	F2, F5
Cannabinoid / Related	CNR1, AKT1, CYP2C9
Salt Sensitivity	GRK4, CLCNKA

127 Medications & Compounds

Full list of supported drugs (click to expand)

Therapeutic Area	Medications
Cardiology & Anticoagulation	warfarin, clopidogrel, rivaroxaban, apixaban, dabigatran, enoxaparin, heparin, nitroglycerin, isosorbide dinitrate, digoxin, amlodipine, losartan, hydrochlorothiazide, chlorthalidone, furosemide
Statins & Lipid-Lowering	simvastatin, atorvastatin, rosuvastatin, pravastatin, ezetimibe, fenofibrate, gemfibrozil, niacin, evolocumab, alirocumab, mipomersen
Psychiatry & Neurology	clozapine, olanzapine, risperidone, haloperidol, aripiprazole, quetiapine, fluoxetine, paroxetine, escitalopram, citalopram, venlafaxine, bupropion, carbamazepine, oxcarbazepine, eslicarbazepine, phenytoin, donepezil, memantine, lecanemab
ADHD & Wakefulness	modafinil, armodafinil, methylphenidate, lisdexamfetamine, amphetamine, atomoxetine, caffeine
Pain & Opioids	codeine, tramadol, fentanyl, morphine, methadone
Oncology	capecitabine, fluorouracil, cisplatin, carboplatin, oxaliplatin, paclitaxel, topotecan, methotrexate, tamoxifen
Immunosuppressants	tacrolimus, azathioprine, mercaptopurine, thioguanine, sulfasalazine
Metabolic & GLP-1	semaglutide, liraglutide, tirzepatide, dulaglutide, setmelanotide, metformin, pioglitazone, rosiglitazone, insulin, orlistat, empagliflozin, dapagliflozin
Infectious Disease	abacavir, efavirenz
Supplements & Vitamins	omega-3/fish oil/EPA/DHA, vitamin D (cholecalciferol, ergocalciferol, calcitriol), vitamin C (ascorbic acid), folic acid, methylfolate, methylcobalamin, beta-carotene, retinol, resveratrol, nicotinamide riboside, NMN, melatonin, pyridoxine
Other	allopurinol, febuxostat, theophylline, tizanidine, cannabidiol, ethanol, disulfiram, celecoxib, ibuprofen, naproxen

19 Disease Risk Conditions

Category	Conditions
Oncology	Prostate Cancer, Breast Cancer (BRCA), Colorectal Cancer, Melanoma
Cardiovascular	Coronary Artery Disease, Atrial Fibrillation
Neurological	Alzheimer's Disease, Parkinson's Disease
Metabolic	Type 2 Diabetes, Hereditary Hemochromatosis, Gout
Autoimmune	Celiac Disease, Psoriasis, Rheumatoid Arthritis, Lupus (SLE)
Hematological	Venous Thromboembolism (Factor V Leiden)
Musculoskeletal	Osteoporosis
Respiratory	Asthma
Ophthalmological	Age-Related Macular Degeneration

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:

Area	What OpenPGx covers
Blood Clotting	Factor V Leiden (F5), Prothrombin mutation (F2), warfarin sensitivity (VKORC1, CYP2C9)
Drug Hypersensitivity	HLA-B57:01 → abacavir, HLA-A31:01 → carbamazepine DRESS, HLA-B*15:02 → SJS/TEN
Statin Myopathy	SLCO1B1 poor transport → simvastatin muscle toxicity
Chemotherapy Toxicity	DPYD deficiency → fluorouracil/capecitabine, TPMT/NUDT15 → thiopurines, GSTP1 → platinum agents
Opioid Response	CYP2D6 poor/ultrarapid → codeine, tramadol, fentanyl dosing
Antipsychotic Side Effects	HTR2C → weight gain risk, DRD2 → efficacy, CYP2D6 → metabolism
Obesity & Weight Loss	FTO, MC4R, BDNF, PCSK1, GHSR, CLOCK, SIRT1, LYPLAL1 — 9 genes affecting appetite, metabolism, fat distribution
Cardiovascular Lipids	APOE, APOA5, APOB, LDLR, LIPC, LPL, SORT1, PNPLA3, TM6SF2 — LDL, HDL, triglycerides, fatty liver
Diabetes & Glucose	GCKR, SLC2A2, MTNR1B, PPM1K, PPARG, IL6 — insulin secretion, glucose sensing, BCAA metabolism
Salt Sensitivity & Hypertension	GRK4, CLCNKA — sodium handling, diuretic response
Circadian & Sleep	PER2, CRY2, NR1D1, CLOCK — chronotype, shift work risk, melatonin response
Vitamin Metabolism	MTHFR → folate, DHCR7 → vitamin D synthesis, BCMO1 → beta-carotene, VDR → vitamin D receptor, SLC23A1 → vitamin C, FUT2 → B12
Omega-3 & Fat Absorption	FADS1 → DHA/EPA conversion, FABP2 → dietary fat absorption
GLP-1 Drug Response	GLP1R, GIPR → semaglutide/tirzepatide efficacy prediction

9 MCP Tools

Tool	Description
upload_genome	Parse raw DNA data (23andMe, Genera)
check_medication	Smart drug lookup — brand names, generics, typos, categories
full_pgx_report	Complete pharmacogenomic report
supplement_protocol	Supplement optimization based on gene variants
compare_medications	Head-to-head drug comparison
check_risk	Check genetic risk for a specific disease
full_risk_report	Comprehensive disease risk report
trait_report	All genetic traits analysis
full_report	Everything combined: medications + risks + traits

---

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: openpgx.schema.json (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 openpgx.schema.json.

Top-level structure:

Field	Required	Role
openpgx_version	yes	Specification version; const 0.4.0
metadata	no	generated_at, generator, sources; optional last_updated
provenance	no	Audit trail: version, previous_version_hash, changelog[] (date, reason, optional description, affected_sections)
patient	no	Profile only (no genotypes): id, raw_data_source, raw_data_format, extraction_date, ancestry
observations	no	Raw measurements: each item has gene, rsid, genotype; optional chromosome, position, diplotype, activity_score
medications	no	Per-drug blocks: drug (name, class, optional brand_names, atc_code, drugbank_id), pgx_associations[], optional interactions[], optional dosing, plus parsed_at, parse_source, confidence (score, evidence_level, …)
risks	no	Disease risk: condition, category (enum incl. oncology, cardiovascular, …), overall_risk, risk_snps[], evidence, actionable, recommendation, studies; optional icd10, polygenic_score, lifetime_risk
traits	no	trait, category, snps[], your_phenotype, description, evidence, practical_advice, studies
fhir_mapping	no	Hints for FHIR: patient_reference, service_request_id, resource_mappings, terminology_systems

Minimal valid skeleton (only the required field):

{
  "openpgx_version": "0.4.0"
}

Example with the 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: openpgx.schema.json

---

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

• 23andMe (.txt) — fully supported
• Genera (.csv) — fully supported
• AncestryDNA — coming soon
• VCF — coming soon

---

Smart Drug Resolution

OpenPGx resolves drug names through 6 layers:

1. Brand > Generic — "Ozempic" > semaglutide (60+ brands including Venvanse, Rivotril, Marevan, Provigil, Stavigile)
2. Generic exact match — "semaglutide" > found
3. Fuzzy brand match — "ozmpic" > Ozempic > semaglutide
4. Fuzzy generic match — "sertralina" > sertraline
5. Category search — "weight loss", "antidepressant", "antidepressivo" > list of drugs
6. Semantic search — pre-computed TF-IDF embeddings (289KB)

---

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

• Specification (OpenPGx format): Apache License 2.0
• Code (MCP server, parsers): MIT 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