M4: Infrastructure for AI-Assisted Clinical Research

M4 Logo

Give your AI agents clinical intelligence & access to MIMIC-IV, eICU, and more

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.

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!

Different setup options

If you don't want to use uv, you can just run pip install m4-infra
If you want to use Docker, look at docs/DEVELOPMENT.md

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'])  # ['admissions', 'diagnoses_icd', ...]

# Query returns a pandas DataFrame
df = execute_query("""
    SELECT icd_code, COUNT(*) as n
    FROM 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 17 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.

Included skills:

API: m4-api for Python API usage
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
Data Quality: Table relationships, MIMIC-eICU mapping, research pitfalls

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

m4 skills                        # Interactive tool selection
m4 skills --tools claude,cursor  # Install for specific tools
m4 skills --list                 # Show installed skills

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

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?"

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
mimic-iv-demo	Tabular	100 patients	Free	Yes	No
mimic-iv	Tabular	365k patients	PhysioNet credentialed	Yes	Yes
mimic-iv-note	Notes	331k notes	PhysioNet credentialed	Yes	Yes
eicu	Tabular	200k+ patients	PhysioNet credentialed	Yes	Yes

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

Switch datasets anytime:

m4 use mimic-iv     # Switch to full MIMIC-IV
m4 status           # Show active dataset details
m4 status --all     # List all available datasets

Setting up MIMIC-IV or eICU (credentialed datasets)

Get PhysioNet credentials: Complete the credentialing process and sign the data use agreement for the dataset.

Download the data:

# For MIMIC-IV
wget -r -N -c -np --cut-dirs=2 -nH --user YOUR_USERNAME --ask-password \
  https://physionet.org/files/mimiciv/3.1/ \
  -P m4_data/raw_files/mimic-iv

# For eICU
wget -r -N -c -np --cut-dirs=2 -nH --user YOUR_USERNAME --ask-password \
  https://physionet.org/files/eicu-crd/2.0/ \
  -P m4_data/raw_files/eicu

The --cut-dirs=2 -nH flags ensure CSV files land directly in m4_data/raw_files/mimic-iv/ rather than a nested physionet.org/files/... structure.

Initialize:
```
m4 init mimic-iv   # or: m4 init eicu
```

This converts the CSV files to Parquet format and creates a local DuckDB database.

Available Tools

M4 exposes these tools to your AI client. Tools are filtered based on the active dataset's modality.

Dataset Management:

Tool	Description
`list_datasets`	List available datasets and their status
`set_dataset`	Switch the active dataset

Tabular Data Tools (mimic-iv, mimic-iv-demo, eicu):

Tool	Description
`get_database_schema`	List all available tables
`get_table_info`	Get column details and sample data
`execute_query`	Run SQL SELECT queries

Clinical Notes Tools (mimic-iv-note):

Tool	Description
`search_notes`	Full-text search with snippets
`get_note`	Retrieve a single note by ID
`list_patient_notes`	List notes for a patient (metadata only)

Guide	Description
Architecture	Design philosophy, system overview, clinical semantics
Code Execution	Python API for programmatic access
Skills	17 clinical research skills and custom skill creation
Tools Reference	MCP tool documentation
BigQuery Setup	Google Cloud for full datasets
Custom Datasets	Add your own PhysioNet datasets
Development	Contributing, testing, code style
OAuth2 Authentication	Enterprise security setup

Roadmap

M4 is infrastructure for AI-assisted clinical research. Current priorities:

Clinical Semantics
- More concept mappings (comorbidity indices, medication classes)
- Semantic search over clinical notes (beyond keyword matching)
- More agent skills that provide meaningful clinical knowledge
New Modalities
- Waveforms (ECG, arterial blood pressure)
- Imaging (chest X-rays)
Clinical Research Agents
- Skills and guardrails that enforce scientific integrity and best practices (documentation, etc.)
- Query logging and session export
- Result fingerprints for audit trails

Troubleshooting

"Parquet not found" error:

m4 init mimic-iv-demo --force

MCP client won't connect: Check client logs (Claude Desktop: Help → View Logs) and ensure the config JSON is valid.

Need to reconfigure:

m4 config claude --quick   # Regenerate Claude Desktop config
m4 config --quick          # Regenerate generic config

Citation

M4 builds on the M3 project. Please cite:

@article{attrach2025conversational,
  title={Conversational LLMs Simplify Secure Clinical Data Access, Understanding, and Analysis},
  author={Attrach, Rafi Al and Moreira, Pedro and Fani, Rajna and Umeton, Renato and Celi, Leo Anthony},
  journal={arXiv preprint arXiv:2507.01053},
  year={2025}
}

Report an Issue · Contribute

M4: Infrastructure for AI-Assisted Clinical Research

M4 Logo

Give your AI agents clinical intelligence & access to MIMIC-IV, eICU, and more

Usage example – M4 MCP | Usage example – Code Execution

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

Why M4?

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

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!

Different setup options

If you don't want to use uv, you can just run pip install m4-infra
If you want to use Docker, look at docs/DEVELOPMENT.md

Code Execution

from m4 import set_dataset, execute_query, get_schema

set_dataset("mimic-iv")

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

# Query returns a pandas DataFrame
df = execute_query("""
    SELECT icd_code, COUNT(*) as n
    FROM 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

Included skills:

API: m4-api for Python API usage
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
Data Quality: Table relationships, MIMIC-eICU mapping, research pitfalls

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

m4 skills                        # Interactive tool selection
m4 skills --tools claude,cursor  # Install for specific tools
m4 skills --list                 # Show installed skills

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

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?"

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
mimic-iv-demo	Tabular	100 patients	Free	Yes	No
mimic-iv	Tabular	365k patients	PhysioNet credentialed	Yes	Yes
mimic-iv-note	Notes	331k notes	PhysioNet credentialed	Yes	Yes
eicu	Tabular	200k+ patients	PhysioNet credentialed	Yes	Yes

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

Switch datasets anytime:

m4 use mimic-iv     # Switch to full MIMIC-IV
m4 status           # Show active dataset details
m4 status --all     # List all available datasets

Setting up MIMIC-IV or eICU (credentialed datasets)

Get PhysioNet credentials: Complete the credentialing process and sign the data use agreement for the dataset.

Download the data:

# For MIMIC-IV
wget -r -N -c -np --cut-dirs=2 -nH --user YOUR_USERNAME --ask-password \
  https://physionet.org/files/mimiciv/3.1/ \
  -P m4_data/raw_files/mimic-iv

# For eICU
wget -r -N -c -np --cut-dirs=2 -nH --user YOUR_USERNAME --ask-password \
  https://physionet.org/files/eicu-crd/2.0/ \
  -P m4_data/raw_files/eicu

The --cut-dirs=2 -nH flags ensure CSV files land directly in m4_data/raw_files/mimic-iv/ rather than a nested physionet.org/files/... structure.

Initialize:
```
m4 init mimic-iv   # or: m4 init eicu
```

This converts the CSV files to Parquet format and creates a local DuckDB database.

Available Tools

M4 exposes these tools to your AI client. Tools are filtered based on the active dataset's modality.

Dataset Management:

Tool	Description
`list_datasets`	List available datasets and their status
`set_dataset`	Switch the active dataset

Tabular Data Tools (mimic-iv, mimic-iv-demo, eicu):

Tool	Description
`get_database_schema`	List all available tables
`get_table_info`	Get column details and sample data
`execute_query`	Run SQL SELECT queries

Clinical Notes Tools (mimic-iv-note):

Tool	Description
`search_notes`	Full-text search with snippets
`get_note`	Retrieve a single note by ID
`list_patient_notes`	List notes for a patient (metadata only)

Guide	Description
Architecture	Design philosophy, system overview, clinical semantics
Code Execution	Python API for programmatic access
Skills	17 clinical research skills and custom skill creation
Tools Reference	MCP tool documentation
BigQuery Setup	Google Cloud for full datasets
Custom Datasets	Add your own PhysioNet datasets
Development	Contributing, testing, code style
OAuth2 Authentication	Enterprise security setup

Roadmap

M4 is infrastructure for AI-assisted clinical research. Current priorities:

Clinical Semantics
- More concept mappings (comorbidity indices, medication classes)
- Semantic search over clinical notes (beyond keyword matching)
- More agent skills that provide meaningful clinical knowledge
New Modalities
- Waveforms (ECG, arterial blood pressure)
- Imaging (chest X-rays)
Clinical Research Agents
- Skills and guardrails that enforce scientific integrity and best practices (documentation, etc.)
- Query logging and session export
- Result fingerprints for audit trails

Troubleshooting

"Parquet not found" error:

m4 init mimic-iv-demo --force

MCP client won't connect: Check client logs (Claude Desktop: Help → View Logs) and ensure the config JSON is valid.

Need to reconfigure:

m4 config claude --quick   # Regenerate Claude Desktop config
m4 config --quick          # Regenerate generic config

Citation

M4 builds on the M3 project. Please cite:

@article{attrach2025conversational,
  title={Conversational LLMs Simplify Secure Clinical Data Access, Understanding, and Analysis},
  author={Attrach, Rafi Al and Moreira, Pedro and Fani, Rajna and Umeton, Renato and Celi, Leo Anthony},
  journal={arXiv preprint arXiv:2507.01053},
  year={2025}
}

Report an Issue · Contribute

M4

M4: Infrastructure for AI-Assisted Clinical Research

Why M4?

Quickstart (3 steps)

1. Install uv

2. Initialize M4

3. Connect your AI client

Code Execution

Agent Skills

Example Questions

Supported Datasets

Available Tools

More Documentation

Roadmap

Troubleshooting

Citation

M4: Infrastructure for AI-Assisted Clinical Research

Why M4?

Quickstart (3 steps)

1. Install uv

2. Initialize M4

3. Connect your AI client

Code Execution

Agent Skills

Example Questions

Supported Datasets

Available Tools

More Documentation

Roadmap

Troubleshooting

Citation