M4: Infrastructure for AI-Assisted Clinical Research

<p align="center"> <img src="webapp/public/m4_logo_transparent.png" alt="M4 Logo" width="180"/> </p> <p align="center"> <strong>Give your AI agents clinical intelligence & access to MIMIC-IV, eICU, and more</strong> </p> <p align="center"> <a href="https://www.python.org/downloads/"><img alt="Python" src="https://img.shields.io/badge/Python-3.10+-blue?logo=python&logoColor=white"></a> <a href="https://modelcontextprotocol.io/"><img alt="MCP" src="https://img.shields.io/badge/MCP-Compatible-green?logo=ai&logoColor=white"></a> <a href="https://github.com/hannesill/m4/actions/workflows/tests.yaml"><img alt="Tests" src="https://github.com/hannesill/m4/actions/workflows/tests.yaml/badge.svg"></a> </p>

M4 is infrastructure for AI-assisted clinical research. Initialize MIMIC-IV, eICU, or custom datasets as fast local databases (with optional BigQuery for cloud access). Your AI agents get specialized tools (MCP, Python API) and clinical knowledge (agent skills) to query and analyze them.

Usage example – M4 MCP | Usage example – Code Execution

M4 builds on the M3 project. Please cite their work when using M4!

Why M4?

Clinical research shouldn't require mastering database schemas. Whether you're screening a hypothesis, characterizing a cohort, or running a multi-step survival analysis—you should be able to describe what you want and get clinically meaningful results.

M4 makes this possible by giving AI agents deep clinical knowledge:

Understand clinical semantics. LLMs can write SQL, but have a harder time with (dataset-specific) clinical semantics. M4's comprehensive agent skills encode validated clinical concepts—so "find sepsis patients" produces clinically correct queries on any supported dataset.

Work across modalities. Clinical research with M4 spans structured data, clinical notes, and (soon) waveforms and imaging. M4 dynamically selects tools based on what each dataset contains—query labs in MIMIC-IV, search discharge summaries in MIMIC-IV-Note, all through the same interface.

Go beyond chat. Data exploration and simple research questions work great via MCP. But real research requires iteration: explore a cohort, compute statistics, visualize distributions, refine criteria. M4's Python API returns DataFrames that integrate with pandas, scipy, and matplotlib—turning your AI assistant into a research partner that can execute complete analysis workflows.

Cross-dataset research. You should be able to ask for multi-dataset queries or cross-dataset comparisons. M4 makes this easier than ever as the AI can switch between your initialized datasets on its own, allowing it to do cross-dataset tasks for you.

Interactive exploration. Some research tasks—like cohort definition—benefit from real-time visual feedback rather than iterative text queries. M4 Apps embed purpose-built UIs directly in your AI client, letting you drag sliders, toggle filters, and see instant results without leaving your workflow.

Quickstart (3 steps)

1. Install uv

macOS/Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Initialize M4

mkdir my-research && cd my-research
uv init && uv add m4-infra
source .venv/bin/activate  # Windows: .venv\Scripts\activate
m4 init mimic-iv-demo

This downloads the free MIMIC-IV demo dataset (~16MB) and sets up a local DuckDB database.

3. Connect your AI client

Claude Desktop:

m4 config claude --quick

Other clients (Cursor, LibreChat, etc.):

m4 config --quick

Copy the generated JSON into your client's MCP settings, restart, and start asking questions!

<details> <summary>Different setup options</summary>

• If you don't want to use uv, you can just run pip install m4-infra

• If you want to use Docker, look at <a href="docs/DEVELOPMENT.md">docs/DEVELOPMENT.md</a>

</details>

Code Execution

For complex analysis that goes beyond simple queries, M4 provides a Python API that returns Python data types instead of formatted strings (e.g. pd.DataFrame for SQL queries). This transforms M4 from a query tool into a complete clinical data analysis environment.

from m4 import set_dataset, execute_query, get_schema

set_dataset("mimic-iv")

# Get schema as a dict
schema = get_schema()
print(schema['tables'])  # ['mimiciv_hosp.admissions', 'mimiciv_hosp.diagnoses_icd', ...]

# Query returns a pandas DataFrame
df = execute_query("""
    SELECT icd_code, COUNT(*) as n
    FROM mimiciv_hosp.diagnoses_icd
    GROUP BY icd_code
    ORDER BY n DESC
    LIMIT 10
""")

# Use full pandas power: filter, join, compute statistics
df[df['n'] > 100].plot(kind='bar')

The API uses the same tools as the MCP server, so behavior is consistent. But instead of parsing text, you get DataFrames you can immediately analyze, visualize, or feed into downstream pipelines.

When to use code execution:

• Multi-step analyses where each query informs the next
• Large result sets (thousands of rows) that shouldn't flood your context
• Statistical computations, survival analysis, cohort characterization
• Building reproducible analysis notebooks

See Code Execution Guide for the full API reference and this example session for a walkthrough.

Agent Skills

M4 ships with a set of skills that teach AI coding assistants clinical research patterns. Skills activate automatically when relevant—ask about "SOFA scores" or "sepsis cohorts" and Claude uses validated SQL from MIT-LCP repositories.

For the canonical list of bundled skills, see src/m4/skills/SKILLS_INDEX.md.

Clinical skills:

• Severity Scores: SOFA, APACHE III, SAPS-II, OASIS, LODS, SIRS
• Sepsis: Sepsis-3 cohort identification, suspected infection
• Organ Failure: KDIGO AKI staging
• Measurements: GCS calculation, baseline creatinine, vasopressor equivalents
• Cohort Selection: First ICU stay identification
• Research Methodology: Common research pitfalls and how to avoid them

System skills:

• M4 Framework: Python API usage, research workflow, skill creation guide
• Data Structure: MIMIC-IV table relationships, MIMIC-eICU mapping

Supported tools: Claude Code, Cursor, Cline, Codex CLI, Gemini CLI, GitHub Copilot

m4 skills                                    # Interactive tool and skill selection
m4 skills --tools claude,cursor              # Install all skills for specific tools
m4 skills --tools claude --tier validated     # Only validated skills
m4 skills --tools claude --category clinical  # Only clinical skills
m4 skills --tools claude --skills sofa-score,m4-api  # Specific skills by name
m4 skills --list                             # Show installed skills with metadata

See Skills Guide for the full list and how to create custom skills.

M4 Apps

M4 Apps bring interactivity to clinical research. Instead of text-only responses, apps render interactive UIs directly in your AI client—ideal for tasks that benefit from real-time visual feedback.

Cohort Builder: Define patient cohorts with live filtering. Adjust age ranges, add diagnosis codes, and toggle clinical criteria while watching counts update instantly.

User: Help me build a cohort of elderly diabetic patients
Claude: [Launches Cohort Builder UI with interactive filters]

M4 Apps require a host that supports the MCP Apps protocol (like Claude Desktop). In other clients, you'll get text-based results instead.

See M4 Apps Guide for details on available apps and how they work.

Example Questions

Once connected, try asking:

Tabular data (mimic-iv, eicu):

• "What tables are available in the database?"
• "Show me the race distribution in hospital admissions"
• "Find all ICU stays longer than 7 days"
• "What are the most common lab tests?"

Derived concept tables (mimic-iv, after m4 init-derived):

• "What are the average SOFA scores for patients with sepsis?"
• "Show KDIGO AKI staging distribution across ICU stays"
• "Find patients on norepinephrine with SOFA > 10"
• "What is the 30-day mortality for patients with Charlson index > 5?"

Clinical notes (mimic-iv-note):

• "Search for notes mentioning diabetes"
• "List all notes for patient 10000032"
• "Get the full discharge summary for this patient"

Supported Datasets

| Dataset | Modality | Size | Access | Local | BigQuery | Derived Tables | |---------|----------|------|--------|-------|----------|----------------| | mimic-iv-demo | Tabular | 100 patients | Free | Yes | No | No | | mimic-iv | Tabular | 365k patients | PhysioNet credentialed | Yes | Yes | Yes (63 tables) | | mimic-iv-note | Notes | 331k notes | PhysioNet credentialed | Yes | Yes | No | | eicu | Tabular | 200k+ patients | PhysioNet credentialed | Yes | Yes | No |

These datasets are supported out of the box. However, it is possible to add any other custom dataset by following these instructions.

Switch datasets or backends anytime:

m4 use mimic-iv     # Switch to full MIMIC-IV
m4 backend bigquery # Switch to BigQuery (or duckdb)
m4 status           # Show active dataset and backend
m4 status --all     # List all available datasets
m4 status --derived # Show per-table derived materialization status

Derived concept tables (MIMIC-IV only):

m4 init-derived mimic-iv         # Materialize ~63 derived tables (SOFA, sepsis3, KDIGO, etc