nonmem-mcp-server

MCP (Model Context Protocol) server for NONMEM pharmacometric modeling workflows. Gives Claude (and any MCP-compatible client) structured access to NONMEM models, results, and simulation tools.

Supports Windows, macOS, and Linux.

Features

Parsing & Analysis (no NONMEM needed)

• read_ext_file — Parse .ext files for parameter estimates, SEs, OFV, condition number
• read_lst_file — Extract termination status, shrinkage, covariance step results
• parse_control_stream — Structural parsing of .ctl/.mod files (THETAs, OMEGAs, $EST options)
• read_nm_dataset — Dataset summary: subjects, observations, missing values
• read_nm_tables — Parse SDTAB/PATAB with statistics for CWRES, ETAs, PRED
• compare_models — Multi-run OFV comparison with delta-OFV and AIC
• summarize_run — Combined .ctl + .ext + .lst summary
• list_runs — Scan project directories for NONMEM runs

Execution & Diagnostics

• submit_run — Start NONMEM runs (async, fire-and-poll pattern)
• check_run_status — Monitor iteration progress via .ext file
• get_run_results — Retrieve parsed results when complete
• cancel_run — Kill running NONMEM jobs
• run_diagnostics — Automated checks: boundary, condition number, shrinkage, RSE
• execute_psn_vpc — Run VPC via PsN (predcorr, stratify, lloq options)
• execute_psn_bootstrap — Run bootstrap via PsN (BCa, stratify)
• check_psn_status — Monitor PsN job progress
• parse_psn_results — Parse existing PsN output directories (no installation needed)
• check_nonmem_setup — Detect NONMEM, PsN, R installation status

Simulation (no NONMEM needed)

• translate_to_mrgsolve — Convert NONMEM .ctl/.mod to mrgsolve model code
• simulate_mrgsolve — Run PK simulations via mrgsolve (R)
• generate_vpc_data — Generate VPC data using mrgsolve + vpc R package
• check_r_setup — Check R and package availability

Prompts

• review_model — Model review checklist
• interpret_results — Pharmacological interpretation
• troubleshoot_run — Diagnose run failures
• suggest_next_model — Suggest next modeling steps
• write_methods_section — Draft publication Methods text

Requirements

• Python 3.12+
• uv (recommended) or pip

Optional

• NONMEM 7.3–7.6 — Required for submit_run (commercial license)
• PsN — Required for execute_psn_vpc, execute_psn_bootstrap
• R with mrgsolve, vpc, dplyr, ggplot2 — Required for simulation and GOF tools

Installation

Using uv (recommended)

git clone https://github.com/sueinchoi/nonmem-mcp-server.git
cd nonmem-mcp-server
uv sync

Using pip

pip install git+https://github.com/sueinchoi/nonmem-mcp-server.git

Or for development:

git clone https://github.com/sueinchoi/nonmem-mcp-server.git
cd nonmem-mcp-server
pip install -e .

NONMEM Path Configuration

The server auto-detects NONMEM from common install locations. If auto-detection fails, set one of these environment variables:

Variable	Description	Example
NONMEM_NMFE_PATH	Full path to nmfe executable	/opt/nm760/run/nmfe76
NONMEM_INSTALL_PATH	NONMEM installation root	/opt/nm760

Auto-detected paths

macOS / Linux:

• /opt/nm760/run/nmfe76, /opt/NONMEM/nm75/run/nmfe75, etc.
• /usr/local/NONMEM/nm76/run/nmfe76
• ~/NONMEM/nm76/run/nmfe76

Windows:

• C:\nm760\run\nmfe76.bat, C:\NONMEM\nm76\run\nmfe76.bat
• C:\Program Files\NONMEM\nm76\run\nmfe76.bat
• D:\NONMEM\nm76\run\nmfe76.bat

Usage with Claude Code

Basic (no NONMEM)

claude mcp add nonmem -- nonmem-mcp

With uv (from source)

claude mcp add -s user nonmem -- \
  uv run --directory /path/to/nonmem-mcp-server python -m nonmem_mcp

With NONMEM path

# macOS / Linux
claude mcp add -s user \
  -e NONMEM_NMFE_PATH=/opt/nm760/run/nmfe76 \
  nonmem -- \
  uv run --directory /path/to/nonmem-mcp-server python -m nonmem_mcp

# Windows (PowerShell)
claude mcp add -s user `
  -e NONMEM_NMFE_PATH=C:\nm760\run\nmfe76.bat `
  nonmem -- `
  uv run --directory C:\path\to\nonmem-mcp-server python -m nonmem_mcp

Verify

claude mcp list
# nonmem: ... - ✓ Connected

Usage with Claude Desktop

Add to claude_desktop_config.json:

macOS / Linux

{
  "mcpServers": {
    "nonmem": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/nonmem-mcp-server", "python", "-m", "nonmem_mcp"],
      "env": {
        "NONMEM_NMFE_PATH": "/opt/nm760/run/nmfe76"
      }
    }
  }
}

Windows

{
  "mcpServers": {
    "nonmem": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\nonmem-mcp-server", "python", "-m", "nonmem_mcp"],
      "env": {
        "NONMEM_NMFE_PATH": "C:\\nm760\\run\\nmfe76.bat"
      }
    }
  }
}

Examples

# Summarize a NONMEM run
"Summarize the run in /path/to/run001/"

# Compare covariate models
"Compare OFV across all models in the covariate analysis directory"

# Diagnose a failed run
"Why did this run fail? Check /path/to/run.lst"

# Systematic model development
"Develop a 2-compartment model with forward IIV addition"

# Translate to mrgsolve for simulation
"Convert my NONMEM model to mrgsolve and run a VPC"

# GOF plots
"Generate GOF plots for run015 with IPRED and CWRES"

Capability Matrix

Feature	No NONMEM	+ NONMEM	+ PsN
Parse .ext/.lst/.ctl	✓	✓	✓
Model comparison	✓	✓	✓
Diagnostics	✓	✓	✓
mrgsolve simulation	✓	✓	✓
mrgsolve VPC	✓	✓	✓
NONMEM execution	✗	✓	✓
PsN VPC	✗	✗	✓
PsN Bootstrap	✗	✗	✓
Parse PsN results	✓	✓	✓

Included Examples

The examples/theopp/ directory contains a complete model development workflow using the Theophylline dataset:

• run001.ctl — 1-compartment base model (ADVAN2, FO)
• run002.ctl — 2-compartment model (ADVAN4 TRANS4)
• run003–005.ctl — 2-comp base models with different initial estimates (no IIV)
• run006–010.ctl — Single IIV forward addition (CL, V2, Q, V3, KA)
• run011–014.ctl — Double IIV forward addition (V2+CL, V2+KA, V2+Q, V2+V3)
• run015.ctl — Final 1-comp model with FOCE+INTER, IPRED, CWRES
• gof_plot_v2.R — GOF plotting script (DV vs PRED/IPRED, CWRES, QQ plot)

License

MIT