r-stats-mcp

An MCP server that gives an LLM the whole of R's statistical toolkit — hypothesis tests, regression, psychometrics, survival analysis, time series and plots — over a persistent R session.

繁體中文說明請見 README.zh-TW.md。

---

What makes it different

One R session, kept alive. Load a dataset once and every later tool call sees it. Fitted models are saved back into that session under a name, so you can fit a model, diagnose it, compare it against another, and then run arbitrary R on it — all without re-reading the data.

Results written for a reader, not a parser. Tools return formatted markdown tables rather than raw JSON: p-values as <.001, effect sizes with magnitude labels, confidence intervals already assembled. When an assumption is violated the output says what to do about it — a significant Levene's test points you at Welch, sparse expected counts bring in Fisher's exact test automatically.

No dead ends. 28 structured tools cover the common ground, and r_run executes arbitrary R in the same session for everything else.

You: Load survey.csv and check whether the two groups differ on score.

  data_load(path="survey.csv", name="df")
  data_inspect(data="df")
  data_transform(data="df", to_factor=["group"])
  check_assumptions(data="df", variables=["score"], group="group")
  test_ttest(data="df", y="score", group="group", nonparametric=true)

---

Requirements

	Version	Notes
R	≥ 4.0	Must be on PATH, or set R_MCP_RSCRIPT
Python	≥ 3.12	Managed by uv
uv	any	Install

Required R packages: jsonlite and evaluate. Everything else is needed only by the tools that use it, and each tool tells you exactly what to install when something is missing.

install.packages(c("jsonlite", "evaluate"))

For full coverage of every tool:

install.packages(c(
  "ggplot2", "ragg", "corrplot",          # plotting
  "car", "emmeans", "rstatix",            # ANOVA, post-hoc, VIF
  "psych", "GPArotation", "lavaan",       # scales, factor analysis, SEM
  "lme4", "lmerTest",                     # mixed models
  "survival", "forecast", "tseries",      # survival, time series
  "mgcv", "MASS", "nnet",                 # GAM, ordinal, multinomial
  "haven", "readxl", "openxlsx",          # SPSS/Stata/Excel
  "sandwich", "lmtest"                    # robust standard errors
))

---

Install

Claude Code

claude mcp add r-stats -- uvx --from git+https://github.com/Ian3738/r-stats-mcp r-stats-mcp

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\):

{
  "mcpServers": {
    "r-stats": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/Ian3738/r-stats-mcp", "r-stats-mcp"]
    }
  }
}

If the client cannot find uvx, give the absolute path (which uvx).

From a clone

git clone https://github.com/Ian3738/r-stats-mcp
cd r-stats-mcp
uv sync
claude mcp add r-stats -- "$(pwd)/run-server.sh"

Configuration

Variable	Default	Purpose
R_MCP_RSCRIPT	Rscript from PATH	Path to the R executable
R_MCP_WORKDIR	Startup directory (home if /)	Where relative paths in data_load resolve
R_MCP_TIMEOUT	180	Default per-call timeout in seconds

Verify the setup by asking the model to call r_session_info.

---

Tools

Session and code

Tool	Purpose
r_run	Execute arbitrary R code; returns console output and plots
r_install_packages	Install packages from CRAN
r_session_info	R version, platform, which statistics packages are available

Data

Tool	Purpose
data_load	CSV, TSV, Excel, SPSS, Stata, SAS, RDS, RData, JSON, Parquet
data_builtin	Datasets bundled with R or an installed package
data_list	Datasets and fitted models currently in the session
data_inspect	Types, missing counts, distinct counts, first rows
data_transform	Filter, derive, recode, factor conversion, sort, long/wide reshape
data_export	Write out as CSV, TSV, Excel or RDS

Descriptives and assumptions

Tool	Purpose
describe	n, mean, SD, SE, CI, median, quartiles, skew, kurtosis — optionally by group
frequency_table	Frequency tables and cross-tabulations with row percentages
check_assumptions	Normality, homogeneity of variance, outliers, VIF, residual diagnostics

Hypothesis tests

Tool	Purpose
test_ttest	One-sample, independent and paired t-tests, with Levene, Cohen's d and rank-based equivalents
test_anova	One-way, factorial, ANCOVA, repeated-measures and mixed designs, with effect sizes and post-hoc comparisons
test_categorical	Chi-square independence and goodness-of-fit, Fisher, McNemar, Cramér's V, odds ratios
test_proportion	One-sample and multi-group proportion tests, including the exact binomial
correlation	Pearson, Spearman, Kendall; partial correlations; multiple-comparison adjustment

Regression and models

Tool	Purpose
regression	Linear, logistic, Poisson, negative binomial, ordinal, multinomial, mixed-effects, GAM
model_diagnostics	Residual normality, heteroscedasticity, autocorrelation, VIF, influential cases
model_compare	AIC, BIC, log-likelihood, ΔAIC, plus nested-model tests
model_predict	Estimated marginal means, or predictions on new data

Scales and questionnaires

Tool	Purpose
reliability	Cronbach's α, McDonald's ω, item-total correlations, α-if-dropped
factor_analysis	EFA and PCA with KMO, Bartlett, parallel analysis, rotated loadings, scree plot
sem	lavaan CFA / SEM / path / growth models with fit indices, CR and AVE
mediation	Bootstrap confidence intervals for indirect effects, multiple mediators supported
moderation	Interaction models with ΔR², simple slopes and an interaction plot

Survival and time series

Tool	Purpose
survival_analysis	Kaplan-Meier with log-rank, Cox regression with the proportional-hazards test
time_series	Stationarity tests, STL decomposition, automatic ARIMA/ETS, forecasts

Plotting

Tool	Purpose
plot	ggplot2 histogram, density, box, violin, scatter, line, bar, Q-Q, correlation heatmap

---

Examples

Regression with model comparison

regression(data="df", dv="score", predictors=["age","sex","group"], save_as="full")
regression(data="df", dv="score", predictors=["age"], save_as="base")
model_compare(models=["base","full"])
model_diagnostics(model="full")

Scale validation

reliability(data="df", items=["q1",...,"q10"], reverse=["q3","q7"], scale_max=5)
factor_analysis(data="df", variables=["q1",...,"q10"])
sem(data="df", type="cfa", model="anxiety =~ q1 + q2 + q3\ndepression =~ q4 + q5 + q6")

Repeated measures

data_transform(data="df", reshape={
  "direction": "long", "value_cols": ["t1","t2","t3"],
  "id_cols": ["id"], "names_to": "time", "values_to": "score"
})
test_anova(data="df", dv="score", within=["time"], id="id", posthoc="bonferroni")

Survival

survival_analysis(data="df", time="days", event="died", group="treatment",
                  type="km", times_of_interest=[180, 365])
survival_analysis(data="df", time="days", event="died",
                  covariates=["age","sex","stage"], type="cox")

---

How it works

MCP client  ──stdio/JSON-RPC──▶  Python server  ──NDJSON over pipes──▶  Rscript worker
                                 (tool schemas)                          (.GlobalEnv)

Transport. A long-lived Rscript process reads newline-delimited JSON requests and writes sentinel-delimited JSON responses. Plots are captured with the evaluate package — the same machinery knitr uses — so base graphics, ggplot2 and lattice all work, and are returned as inline PNGs.

Namespace hygiene. User objects live in .GlobalEnv; the server's own machinery lives in a separate .rmcp_sys environment. data_list and r_run therefore see only your data and models.

Timeouts. Two layers: R enforces its own limit with setTimeLimit(), and Python applies a hard timeout on the pipe. If the session has to be restarted, the tool says so explicitly rather than silently losing your data.

Failure messages are actionable. Passing a three-level factor to a t-test does not produce a stack trace — it tells you the levels it found and points you at test_anova.

---

Development

uv sync
uv run python -c "
import asyncio
from r_stats_mcp.server import server
print(len(asyncio.run(server.list_tools())), 'tools')
"

Adding a statistical tool means two edits: an R helper in src/r_stats_mcp/R/ returning list(md=, plots=), and a decorated function in server.py describing its parameters. The R files are sourced in filename order at worker startup.

src/r_stats_mcp/
├── server.py          MCP tool definitions and schemas
├── session.py         persistent R subprocess, transport, timeouts
└── R/
    ├── worker.R           protocol loop, plot capture
    ├── 00-util.R          markdown tables, formatting, session objects
    ├── 10-data.R          loading, inspection, reshaping
    ├── 20-descriptive.R   descriptives, frequencies, assumptions
    ├── 30-htest.R         t-tests, ANOVA, categorical, correlation
    ├── 40-regression.R    regression family, diagnostics, comparison
    ├── 50-psychometrics.R reliability, factor analysis, SEM, mediation
    ├── 60-survival-ts.R   survival analysis, time series
    └── 70-viz.R           ggplot2 charts

License

MIT — see LICENSE.