causalMCP

An MCP (Model Context Protocol) server for causal effect estimation from observational data. Powered by CausalPFN and EconML.

Estimate treatment effects, compare causal models, and rank units for targeting — all through natural language via your AI assistant.

What It Does

causalMCP lets you answer causal questions directly from CSV data:

• "Did this marketing campaign actually increase purchases?" → ATE estimation

• "Which customers benefited most from the intervention?" → Uplift ranking

• "How do different causal models agree on the treatment effect?" → Model comparison

No ML expertise required. Just point it at your data and ask.

Tools

Core Estimation (CausalPFN)

Model Training & Comparison

Supported Models

• CausalPFN — Pretrained transformer for amortized causal inference (zero-shot, no training needed)

• S-Learner — Single model for both treatment groups (via EconML)

• T-Learner — Separate models per treatment group (via EconML)

• X-Learner — Two-stage estimator, good with imbalanced treatment (via EconML)

• DML (Double Machine Learning) — Orthogonal/debiased estimation with analytical CIs (via EconML)

Each metalearner supports random_forest or gradient_boosting as the base learner.

Intelligent Caching

All fitted models and computed results (CATE arrays, ATE values, confidence intervals) are cached in memory. This means:

• Calling estimate_cate then estimate_ate on the same data → ATE is derived from cached CATE instantly

• Calling train_model then compare_models → already-trained models are reused

• Calling get_cached_estimate with a model_id → instant retrieval, no re-inference

• Cache keys include data path, covariates, treatment/outcome columns, and model name — different data or different models always get separate entries

Installation

pip install causalMCP

Requirements

• Python 3.10+

• Works on macOS (Intel & Apple Silicon), Linux, and Windows

• GPU optional (CausalPFN uses CPU by default, auto-detects CUDA if available)

Configuration

Kiro

Add to .kiro/settings/mcp.json:

{
  "mcpServers": {
    "causalmcp": {
      "command": "causalmcp",
      "env": {
        "OMP_NUM_THREADS": "1"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "causalmcp": {
      "command": "causalmcp",
      "env": {
        "OMP_NUM_THREADS": "1"
      }
    }
  }
}

Cline (VS Code)

{
  "mcpServers": {
    "causalmcp": {
      "command": "causalmcp",
      "type": "stdio",
      "env": {
        "OMP_NUM_THREADS": "1"
      }
    }
  }
}

Claude Code

{
  "mcpServers": {
    "causalmcp": {
      "command": "causalmcp"
    }
  }
}

Apple Silicon (M1/M2/M3/M4): The OMP_NUM_THREADS=1 environment variable prevents FAISS/OpenMP threading conflicts that cause segfaults. Always include it on macOS.

Environment Variables

Usage Examples

Once configured, ask your AI assistant questions like:

Estimate Individual Treatment Effects

"Estimate the causal effect of the marketing campaign on purchase amount using /path/to/data.csv. Covariates are age, income, and previous_purchases. Treatment is 'received_email', outcome is 'purchase_amount'."

Run Diagnostics Before Estimation

"Run causal diagnostics on my dataset to check if the assumptions are reasonable before estimating effects."

Train and Compare Multiple Models

"Train an S-Learner and a T-Learner on my data, then compare their ATE estimates."

Compare All Models Side by Side

"Compare all causal models (CausalPFN, S-Learner, T-Learner, X-Learner, DML) on my experiment data and show me the CATE correlations."

Uplift Ranking with a Specific Model

"Using the T-Learner model we just trained, rank customers by who would benefit most from the promotional offer."

Retrieve Cached Results

"Show me the CATE estimates from the DML model we trained earlier."

Data Format

Your CSV needs three types of columns:

Example CSV:

age,income,previous_purchases,received_email,purchase_amount
35,55000,3,1,125.50
42,72000,5,0,80.00
28,45000,1,1,95.00
51,68000,8,0,110.00
33,42000,2,1,75.00

Data Handling

• Missing values are imputed with median (numeric) or rows are dropped (non-numeric)

• Large datasets are automatically subsampled with stratified sampling to preserve treatment ratio

• Minimum 20 rows required; warning below 100 rows

• Both treatment and control groups must be present

Important Assumptions

⚠️ Strong Ignorability Required: All estimators assume that the covariates you provide capture ALL variables that jointly affect both treatment assignment and outcome (no unobserved confounders).

This is a fundamental assumption of causal inference from observational data that cannot be verified from data alone. Domain expertise is required to assess whether this assumption is plausible for your specific application.

Model agreement (from compare_models) does not validate this assumption — all models share it.

How It Works

┌─────────────────────────────────────────────────────┐
│                    MCP Client                        │
│            (Kiro, Claude Desktop, etc.)              │
└──────────────────────┬──────────────────────────────┘
                       │ MCP Protocol (stdio)
┌──────────────────────▼──────────────────────────────┐
│                  causalMCP Server                     │
│                                                      │
│  ┌─────────────┐  ┌─────────────┐  ┌──────────────┐ │
│  │estimate_cate│  │ train_model │  │compare_models│ │
│  │ estimate_ate│  │get_cached_  │  │  diagnostics │ │
│  │uplift_rank  │  │  estimate   │  │              │ │
│  └──────┬──────┘  └──────┬──────┘  └──────┬───────┘ │
│         │                │                │          │
│  ┌──────▼────────────────▼────────────────▼───────┐  │
│  │              ModelCache (in-memory)             │  │
│  │   Caches fitted models + CATE/ATE/CI results   │  │
│  └──────┬─────────────────────────┬───────────────┘  │
│         │                         │                  │
│  ┌──────▼──────┐          ┌───────▼───────┐          │
│  │  CausalPFN  │          │   EconML      │          │
│  │ (pretrained │          │ (S/T/X-Learner│          │
│  │ transformer)│          │    + DML)     │          │
│  └─────────────┘          └───────────────┘          │
└──────────────────────────────────────────────────────┘

Development

git clone https://github.com/yourusername/causalMCP.git
cd causalMCP
pip install -e ".[dev]"
pytest tests/

License

Apache 2.0

Citation & Acknowledgments

This package wraps CausalPFN by Balazadeh Meresht et al. — a pretrained transformer for amortized causal effect estimation. If you use CausalPFN in your work, please cite:

@article{balazadeh2024causalpfn,
  title={CausalPFN: Amortized Causal Effect Estimation},
  author={Balazadeh Meresht, Vahid and Syrgkanis, Vasilis and Krishnan, Rahul G.},
  year={2024}
}

Metalearner implementations are provided by EconML (Microsoft Research).