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.

• A companion skill at skills/econ-r/SKILL.md that guides agents through research design, diagnostics, robustness, and artifact-backed interpretation.

Related MCP server: Friday MCP Server

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.

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.

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

This repository is prepared for public GitHub publication, but no remote has been created and nothing has been published.