# mplus-mcp

[![test](https://github.com/Ian3738/mplus-mcp/actions/workflows/test.yml/badge.svg)](https://github.com/Ian3738/mplus-mcp/actions/workflows/test.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
[![Mplus 8](https://img.shields.io/badge/Mplus-8-1f6feb.svg)](https://www.statmodel.com/)

An MCP server that drives [Mplus](https://www.statmodel.com/): it prepares data,
writes and runs input files, and reads the output back as tables instead of
several hundred lines of fixed-width text.

Works with the licensed executable and with Mplus Demo (which caps the model at
6 dependent and 2 independent variables).

繁體中文說明請見 [README.zh-TW.md](README.zh-TW.md)。

---

## Tools

| Tool | What it does |
| --- | --- |
| `mplus_status` | Which executable is in use, its version, demo limits |
| `syntax_help` | Syntax reference by topic (model, mixture, invariance, errors …) |
| `data_prepare` | CSV/Excel/SPSS/Stata → an Mplus `.dat` plus the VARIABLE block |
| `build_syntax` | Input syntax for cfa, efa, path, sem, mediation, growth, lpa, lca, invariance, twolevel |
| `run_syntax` | Write syntax to a file, run it, summarise the output |
| `run_file` | Run an existing `.inp` |
| `output_summary` | Re-read any `.out`: fit, estimates, warnings |
| `output_section` | One section verbatim (TECH1, residuals, random starts …) |
| `compare_fit` | Fit indices side by side, with a scaled chi-square difference test |
| `savedata_read` | Read back factor scores / class probabilities, optionally as CSV |

## Install

Needs [uv](https://docs.astral.sh/uv/) and an installation of Mplus. The demo
build works too.

### Claude Code

```bash
claude mcp add mplus -- uvx --from git+https://github.com/Ian3738/mplus-mcp mplus-mcp
```

### Claude Desktop

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

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

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

### From a clone

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

`run-server.sh` exists for two situations a bare `uv run` does not handle: GUI
clients that start without `uv` on PATH, and clones inside iCloud Drive, where
the virtualenv has to live outside the synced folder.

### Configuration

| Variable | Default | Purpose |
| --- | --- | --- |
| `MPLUS_MCP_BINARY` | first executable found (see below) | Path to the Mplus executable. Set it to prefer a licensed copy over the demo. |
| `MPLUS_MCP_WORKDIR` | `~/Mplus-MCP` | Where runs go when no folder is given |

Searched automatically: `mplus` / `mpdemo` on PATH, `/Applications/Mplus/mplus`,
`/Applications/MplusDemo/mpdemo`, `/usr/local/bin/mplus`, `/opt/mplus/mplus`,
`C:\Program Files\Mplus\Mplus.exe`.

Reading `.sav` files needs one extra package: add `--extra spss` to `uv sync`, or
use `uvx --from "git+https://github.com/Ian3738/mplus-mcp[spss]" mplus-mcp`.

Verify the setup by asking the model to call `mplus_status`.

## How a session goes

```
data_prepare(path="ses.csv")
  → writes ses.dat, reports that `motivation` became `motivat`, hands back
    NAMES = id sex y1 y2 y3 y4 x1 x2; MISSING = ALL (-999);

build_syntax(model_type="cfa", data_file="ses.dat",
             names="id sex y1-y4 x1 x2",
             factors={"F1": ["y1", "y2", "y3", "y4"]})
  → the input file as text

run_syntax(syntax=..., workdir="/path/holding/ses.dat", name="cfa1")
  → status, fit table, parameter estimates, any warnings, and cfa1.out on disk

compare_fit(out_paths=["cfa1.out", "cfa2.out"], chisq_diff=True)
```

## Notes on Mplus itself

- Data files are resolved relative to the folder the input file runs in, so the
  server always runs with the working directory set to the `.inp` folder and
  refers to data by its bare file name. That is what makes folder names with
  spaces work.
- Input lines are capped at 90 characters; `run_syntax` folds longer ones.
- Variable names are capped at 8 characters; `data_prepare` renames and reports.
- A run that fails still writes an `.out`, so the error is parsed and returned
  with the well-known causes attached where they apply.

## Licence

MIT