econ-r-mcp

econ-r-mcp is a local MCP server plus companion skill for reproducible applied econometrics and statistics workflows powered by headless R execution.

The core rule is that an LLM must not fabricate empirical output. Coefficients, standard errors, p-values, diagnostics, tables, plots, model comparisons, and report text should be grounded in executed R code and saved artifacts.

What It Provides

• A Python FastMCP server named econ-r-mcp.
• Narrow, auditable MCP tools for R and Quarto workflows.
• Workspace-restricted file access with path traversal protection.
• Per-run artifact folders containing scripts, logs, session info, package versions, result JSON, tables, plots, and reports.
• Curated local econometrics guidance lookup for method tags such as iv, did, rd, panel_fe, synthetic_control, time_series, and forecasting.
• First-class lookup for the locally installed AER package's Applied Econometrics with R companion materials, including package vignette/errata files, chapter demo scripts, datasets, and help/index materials.
• A companion skill at skills/econ-r/SKILL.md that guides agents through research design, diagnostics, robustness, and artifact-backed interpretation.

Prerequisites

• Python 3.11 or newer.
• R with Rscript available on PATH.
• Optional: Quarto for .qmd report rendering.
• Optional R packages, installed as needed from the allowlist: fixest, modelsummary, broom, marginaleffects, did, rdrobust, Synth, gsynth, plm, AER, sandwich, lmtest, clubSandwich, estimatr, MatchIt, cobalt, WeightIt, vars, forecast, fable, tsibble, urca, tseries, strucchange, ggplot2, patchwork, gt, kableExtra, haven, readxl, arrow, DBI, and RPostgres.

jsonlite is a core runtime dependency for structured result JSON.

For textbook-grounded guidance, install AER. The server does not bundle or scrape an external textbook; it inspects the local R package installation and returns only source paths/materials that are actually present on disk.

Installation

From this repository:

uv sync --extra dev
uv run econ-r-mcp

Or install into an environment:

python -m pip install .
econ-r-mcp

Run a local health check through Python:

uv run python - <<'PY'
from econ_r_mcp.tools import health_check_impl
print(health_check_impl())
PY

Configuration

The server scopes file operations to configured workspace roots.

Use environment variables:

export ECON_R_MCP_ALLOWED_ROOTS="/absolute/path/to/my/project"
export ECON_R_MCP_CONFIG="/absolute/path/to/econ-r-mcp/config/econ-r-mcp.toml"

Or edit config/econ-r-mcp.toml.

Important settings:

• allowed_workspace_roots: absolute roots the tools can read/write.
• allowlisted_r_packages: packages install_r_packages may install.
• allowed_env_vars: environment variables the caller may pass into R.
• guidance_roots: optional local curated Markdown guidance directories.
• default_timeout_seconds and max_output_bytes: execution and response caps.

Connecting MCP Clients

Claude Desktop-style JSON

{
  "mcpServers": {
    "econ-r-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/econ-r-mcp",
        "run",
        "econ-r-mcp"
      ],
      "env": {
        "ECON_R_MCP_ALLOWED_ROOTS": "/absolute/path/to/your/econ-project"
      }
    }
  }
}

Codex or Other Local MCP Clients

Use stdio transport and run:

uv --directory /absolute/path/to/econ-r-mcp run econ-r-mcp

Set ECON_R_MCP_ALLOWED_ROOTS to the empirical project directory before launching the client.

Tool List

• health_check: checks R, Rscript, Quarto, and R package availability.
• init_project: creates data/, scripts/, reports/, outputs/tables/, outputs/plots/, outputs/models/, and logs/; optionally initializes renv.
• install_r_packages: installs only allowlisted R packages and returns structured results.
• run_r_script: runs a project .R script under the artifact harness.
• render_quarto: renders .qmd reports to HTML, PDF, or DOCX when Quarto supports it.
• inspect_dataset: inspects CSV, TSV, RDS, Parquet, or Stata files.
• run_regression_fixest: runs fixest::feols or fixest::feglm.
• run_iv: runs IV regression with fixest syntax and first-stage output.
• run_did: supports TWFE event studies and Callaway-Sant'Anna through did.
• run_rdrobust: runs rdrobust, RD plots, and density tests where available.
• run_panel_diagnostics: checks panel balance, duplicate keys, missing periods, and treatment timing.
• run_time_series_diagnostics: creates plots, ACF/PACF, unit-root checks, and structural-break checks where packages are available.
• create_modelsummary: creates publication-style tables from saved model objects or result JSON.
• read_artifact: reads saved logs, JSON, tables, Markdown, HTML, or TeX without executing code.
• list_artifacts: lists run outputs with pagination.
• reproduce_run: reruns a previous saved script and compares result JSON hashes.
• lookup_econometrics_guidance: returns concise, cited local guidance for econometric methods. Use method="aer_textbook" to inspect the locally installed AER package's Applied Econometrics with R companion materials.

Local AER Guidance

lookup_econometrics_guidance prefers deterministic method files for tags such as iv, did, and rd. When AER is installed, tagged responses also include an aer_reference block with local AER package source paths where relevant.

Use this explicit lookup for AER grounding:

{
  "method": "aer_textbook",
  "query": null,
  "corpus_root": null
}

The response distinguishes retrieved textbook/package guidance from executed empirical results. It should not be used to invent coefficients, diagnostics, plots, or sample facts.

Artifact Layout

Each R or Quarto run writes to:

outputs/models/<tool>-<timestamp>-<id>/
  input_script.R
  executed_script.R
  stdout.log
  stderr.log
  combined.log
  session_info.txt
  package_versions.csv
  result.json
  run_metadata.json
  tables/
  plots/
  reports/

Security Model

• No arbitrary shell execution tool is exposed.
• R and Quarto are invoked with argv lists, not shell strings.
• File paths are resolved and checked against allowed workspace roots.
• Project paths cannot escape the project root.
• User-provided R scripts are copied before execution.
• Generated R code is saved before execution.
• Dangerous R operations such as system(), system2(), unlink(), download.file(), and common network/process packages are blocked by default.
• Environment variables supplied to R must be explicitly allowlisted.
• Tool responses summarize logs and link artifacts; full logs stay in the artifact folder.

R itself is a powerful language, so run this server only for trusted projects and review user-supplied scripts before setting allow_dangerous_code=true.

Example Workflows

Fixed Effects Regression

User request:

Inspect this dataset, suggest an empirical strategy, run a fixed-effects model with clustered SEs, produce a modelsummary table, and render a Quarto report.

Tool sequence:

1. init_project
2. inspect_dataset(data_path="data/fe_panel.csv", id_columns=["unit"], time_column="year")
3. run_panel_diagnostics(data_path="data/fe_panel.csv", unit="unit", time="year")
4. run_regression_fixest(data_path="data/fe_panel.csv", formula="y ~ x", fixed_effects=["unit", "year"], cluster_vars=["unit"])
5. create_modelsummary(model_paths=["outputs/models/<run>/model.rds"], notes=["SE clustered by unit", "Unit and year FE included"])
6. render_quarto(qmd_path="reports/example_report.qmd", output_format="html")

DiD Event Study

Use run_did with method="twfe_event_study" after inspect_dataset and run_panel_diagnostics.

Required interpretation items:

• ATT/event-study estimand.
• Treatment timing summary.
• Treated/control counts.
• Pre-trend plot if produced.
• Warning about staggered TWFE bias.
• Artifact paths for result JSON and event-study plot.

IV Regression

Use run_iv with explicit outcome, endogenous, instruments, controls, fixed effects, and cluster variables.

Required interpretation items:

• First-stage table.
• Weak-instrument diagnostics where available.
• Robust or clustered SE choice.
• Exclusion restriction stated as an assumption.
• Overidentification tests where applicable.

Regression Discontinuity

Use run_rdrobust with outcome, running variable, cutoff, covariates if justified, kernel, and polynomial order.

Required interpretation items:

• Cutoff, bandwidths, kernel, and order.
• Conventional and robust estimates.
• RD plot.
• Density/manipulation check if available.
• Local nature of the estimand.

Quarto Report Generation

Place .qmd files in reports/, then call:

{
  "project_root": "/absolute/path/to/project",
  "qmd_path": "reports/example_report.qmd",
  "output_format": "html"
}

The rendered files are saved under the run artifact reports/ folder.

Companion Skill

The skill lives at:

skills/econ-r/SKILL.md

Install or reference it in clients that support local skills. It instructs the agent to behave like a careful applied econometrician and to use this MCP server for artifact-grounded empirical output.

Tests

Run unit tests:

uv run --extra dev pytest -m "not integration"

Run integration tests that execute optional R packages:

uv run --extra dev pytest -m integration

Integration tests skip with clear messages when optional R packages are not installed.

Limitations

• Static blocking of dangerous R code is a guardrail, not a sandbox.
• Some diagnostics depend on optional R packages.
• The server does not decide whether a design is causally credible; it forces the agent to state assumptions and verify artifacts.
• Semantic retrieval is intentionally lightweight and local-only; deterministic method tags are preferred.
• Quarto PDF rendering depends on the local Quarto and LaTeX setup.

Publication Status

Public GitHub repository: https://github.com/emmanueltsallis/econ-r-mcp

Review generated artifacts and local-only files before publishing release builds.