statlab-mcp — Statistical Analysis MCP Server

Standalone project, not affiliated with any vendor's official plugin (README historical note: not affiliated with DeepSeek Harness). Gives AI agents (Claude Code / Cursor / DeepSeek Harness / Codex, etc.) real statistical capability: LLMs computing statistics by mental math will fabricate numbers; every statistical result in this project comes from real computation (numpy / scipy / statsmodels / scikit-learn / pmdarima), the AI only handles invocation and interpretation; no LLM is allowed to participate in computation within the first layer of 25 tools.

What it's for

After installing it, when you tell the AI "help me analyze this sales data", the AI no longer makes groundless assertions — it calls 25 real statistical tools: compute descriptive statistics, check correlations, run hypothesis tests, fit regressions, perform clustering, forecast time series, draw Chinese charts — every number comes from a validated statistical library, reproducible and accountable. The summary field gives a one-sentence Chinese conclusion, and result gives the full structured data, e.g.:

{"status": "ok", "result": {"p_value": 0.0241, "mean_diff": 5.5, "effect_size": 0.65},
 "summary": "Welch t 检验：均值差 5.5（95% CI [0.74, 10.26]），p=0.0241 <0.05 拒绝 H0……相关≠因果"}

Related MCP server: shewhart-mcp

Who it's for

What problems it solves

Features and standout capabilities

1. Determinism above all: all random processes fixed with seed (42); running the same file twice yields byte-for-byte identical results (this is the foundation of accountability, with dedicated assertions in tests)

2. Anti-hallucination design: the first layer of 25 tools has zero LLM involvement; conclusion copy is generated by code templates assembling numbers; p<0.001 is uniformly shown as "<0.001"; every conclusion is accompanied by a fixed limitations statement (correlation ≠ causation, whether corrected, sample size)

3. Caliber locked down and recomputable: q1/q3 = linear interpolation (same caliber as Excel QUARTILE.INC), skewness/kurtosis = scipy Fisher caliber, std = ddof=1 (Excel STDEV.S) — documented in writing, tests cross-check against manual formulas and standard libraries independently (223 pytest cases, coverage in docs/)

4. Full Chinese pipeline: Chinese column names, automatic GBK encoding fallback, Chinese-font charts (falls back to English with a note when no font is available), Chinese error messages with solution suggestions

5. Hardcore security and protection: local files only, rejects UNC/NUL paths, no network upload, triple protection at >50MB / 2 million rows / 500MB memory, xlsx zip-bomb and date-span protection, error output capped (prevents malicious input from hanging the process)

6. Uniform calling experience: all tools are isomorphic (parameter validation → Chinese error or result+summary), so both agents and humans pick it up painlessly; MCP tool descriptions = full docstring (parameter tables/return structure/examples), when the agent opens the tool list, that is the user manual

7. Engineering completeness: 12 design documents (per-tool parameter tables/boundary tables/JSON Schema/validation methods) + client integration configs + coverage of 82–96% + full ruff pass + stdio protocol smoke test

Quick start

# 1. 安装（Python 3.13+，仅 pip）
git clone https://github.com/good-boy4069/statlab-mcp.git
cd statlab-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt --timeout 60

# 2. 验证能跑（应输出 ALL-STDIO-OK）
$env:PYTHONUTF8="1"
.\.venv\Scripts\python.exe tests\smoke_stdio.py

Connect to Claude Code (project root .mcp.json):

{
  "mcpServers": {
    "statlab-mcp": {
      "command": "C:\\path\\to\\statlab-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "statlab_mcp.server"],
      "cwd": "C:\\path\\to\\statlab-mcp",
      "env": {"PYTHONUTF8": "1"}
    }
  }
}

Three musts: -m statlab_mcp.server (not the server.py path), cwd pointing to the project root, and PYTHONUTF8=1. Other clients (Cursor/VSCode/Codex/Hermes/DSH) see docs/clients.md.

First call (usable directly from the command line without a client):

.\.venv\Scripts\python.exe -c "import sys; sys.path.insert(0,'.'); from statlab_mcp.tools.data_exploration_describe_statistics import describe_statistics; import json; print(json.dumps(describe_statistics('samples/clean.csv'), ensure_ascii=False, indent=1))"

Three iron rules for data: ① only csv/xlsx/tsv/json accepted, absolute paths freely given (Chinese/GBK/empty values/invalid dates all handled automatically); ② put real data outside the project directory; ③ for every statistic, first read the plain-Chinese conclusion in summary, then flip through the structured numbers in result.

The 25 tools at a glance

Core value and unified protocol

• Accountable numbers: results are deterministic, reproducible, and testable; the same input run twice gives identical results (global seed=42)

• Unified structure: success {status:"ok", result:{...}, summary:"one-sentence Chinese conclusion"}; failure {status:"error", message:"Chinese reason with a useful hint"}

• Image attachments: image-bearing tools attach __image__ at the top level of the returned JSON (absolute image path, base64 forbidden)

Environment preparation (Windows)

1. Requires Python 3.13+, a dedicated virtual environment (pip only; uv/poetry/conda forbidden):

   python -m venv .venv
   .\.venv\Scripts\Activate.ps1
   pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt --timeout 60

2. requirements.txt is the single authoritative source for dependencies (pyproject.toml holds only metadata).

3. UTF-8 must be set before running (otherwise stdio writes Chinese JSON in GBK and the MCP connection breaks immediately):

   $env:PYTHONUTF8="1"

   As a fallback, the server entry file also has sys.stdout.reconfigure(encoding="utf-8") at the very top.

4. Data reading uniformly goes through the read_table() wrapper: utf-8-sig trial read → on csv/tsv failure automatically switch to gbk → on further failure a Chinese error "file encoding unrecognized, please save as UTF-8"; format whitelist {csv, xlsx, tsv, json}, xlsx reads only the first sheet.

How agents view images

• DeepSeek Harness: use the read_image tool to read the absolute path returned by __image__

• Claude Code: use the Read tool to read the same path

• All images are stored in reports/plots/YYYYmmdd/ (archived by date to prevent buildup), filenames toolname_<primary column name or all>_YYYYmmdd_HHMMSS_fff.png, Chinese fonts Microsoft YaHei/SimHei (falls back to English with an in-chart note when missing), dpi=150; the directory may be cleaned at any time (does not affect any computation)

Security statement

• Only analyzes locally provided data files that you actively hand over; rejects UNC/NUL paths; no network uploads whatsoever

• Path trust statement: tools do not verify file provenance (they read directly from the path you give), so do not pass paths from untrusted sources; put real data outside the project directory

• Big-data protection: >50MB rejected; 5–50MB first estimates row count/memory and rejects if over limit; zip bombs and date-span attack surfaces also hard-protected

Testing and acceptance

& .\.venv\Scripts\python.exe -m pytest tests\ -q

• Test data is generated by tests/make_fixtures.py with fixed seed and committed to the repo; key numbers are cross-checked against independent third-party computation (statistics.mean / manually computed expected-value tables) — no circular reasoning allowed

• Acceptance workflow (AI-assisted mode since 2026-08-26): full pytest pass + real-run verification on two datasets (full real stdout archived in the acceptance record) → commit + PROGRESS entry; users retain the right to spot-check at any time

• Quality baseline: 223 pytest cases, tool module coverage 82–96%, full ruff pass, stdio protocol smoke ALL-STDIO-OK

Technical notes (mcp 2.x)

Dependency pinned to mcp==2.1.0: mcp.server.fastmcp.FastMCP has been superseded by mcp.server.mcpserver.MCPServer (API-compatible add_tool/tool decorators; list_tools/call_tool/run_stdio_async are async).

Documentation navigation

• docs/clients.md — client integration configs (Claude Code/Cursor/VSCode/Codex/Hermes/DSH)

• docs/SPEC.md — protocol and statistical calibers (return structure/number protocol/image protocol/behavior contract)

• docs/design/ — interface design for each tool (parameter tables/boundary behavior tables/JSON Schema/validation methods, the user manual for agents and secondary developers)

• docs/example_report.md — example report for auto_analysis scheme A (a demonstration of the anti-hallucination iron rules)

Directory structure

statlab_mcp/          # server.py（只注册工具+to_jsonable）+ tools/<组>_<工具>.py
docs/                  # SPEC.md（协议与统计口径）、design/（各工具接口设计文档）、clients.md（接入配置）
samples/               # 入库样例数据 + 生成脚本
tests/                 # pytest + fixtures 生成脚本
data/                  # 使用者亲手造的测试数据（gitignore，不入库）
reports/plots/         # 图片输出（gitignore，按日期归档可随时清理）

License

MIT (Copyright © 2026 周翔宇).