spss-mcp (macOS + Windows)

让 SPSS 成为 Agent 的「统计引擎 + 制图工厂」：论文级图片、深度结果解析、方法真机验证、安全执行。

简体中文 ｜ English

面向 IBM SPSS Statistics 的 MCP（Model Context Protocol）服务器，供 Cursor / Claude Code / Codex 等 Agent 调用本机 SPSS。

本仓库基于上游 flupke91/spss-studio-mcp（MIT），在其能力之上增加了 macOS / SPSS 27+ 适配与若干兼容性修复，并在 macOS + IBM SPSS Statistics 27 真机验证通过。

能力概览

• 论文级出图：11 类 spss_chart_*，PNG / TIFF / EMF（1950×1500 @300 dpi）
• 深度结果解析：OMS 文本 → Markdown + JSON + 统计摘要
• 分析方法：描述 / t / ANOVA / 回归 / 因子 / 信度 / 生存 / 混合模型 / 中介调节等
• 安全执行：危险命令拦截、路径白名单、dry_run、审计日志
• 跨平台引擎：Windows（stats.exe）与 macOS（SPSS Statistics.app + 捆绑 Python3 XD）

本 fork 相对上游的主要改动

系统要求

• Python 3.10+
• 本机已授权的 IBM SPSS Statistics（已在 27（macOS） 验证；上游在 32（Windows） 验证）
• macOS：安装包内需含 Resources/Python3（XD API）

快速开始

优先从 PyPI 安装（无需 clone）：

pip install spss-mcp
# 或：uv pip install spss-mcp
spss-mcp status   # 应显示 SPSS batch / python: OK

免安装即跑（类似 npx）：

uvx spss-mcp status
uvx spss-mcp serve

macOS 若未自动发现安装，可设置：

export SPSS_INSTALL_PATH="/Applications/IBM SPSS Statistics 27"

配置 Cursor（~/.cursor/mcp.json）：

{
  "mcpServers": {
    "spss-mcp": {
      "command": "uvx",
      "args": ["spss-mcp", "serve", "--transport", "stdio"],
      "env": {
        "SPSS_INSTALL_PATH": "/Applications/IBM SPSS Statistics 27"
      }
    }
  }
}

也可用已安装的命令："command": "spss-mcp", "args": ["serve", "--transport", "stdio"]。

辅助配置：

spss-mcp configure-cursor   # 写入 ~/.cursor/mcp.json
spss-mcp configure-claude
spss-mcp configure-codex
spss-mcp setup-info

开发者本地可编辑安装：git clone 后执行 pip install -e ".[dev]"。

自然语言示例

对 examples/data/experiment_study.sav 做独立样本 t 检验（group 分组，posttest）
用 examples/data/mediation_study.sav 做中介分析：autonomy → satisfaction → performance
画 examples/data/survey_study.sav 学习投入总分的直方图（带正态密度），PNG 300dpi
对 examples/data/long_study.sav 做混合模型：score ~ group + time，随机截距 subject=id

纵向数据约定：

• 重复测量 ANOVA（宽表）：examples/data/longitudinal_study.sav（time1/time2/time3）
• MIXED（长表）：examples/data/long_study.sav（id/time/score）

架构

MCP 客户端（Cursor / Claude Code / Codex）
        │  MCP 协议（stdio）
        ▼
工具层    50+ 工具：文件/元数据 · 分析方法 · 图表 · 中介/调节
        ▼
语法构建   方法模板 + Pydantic 校验 ｜ 安全层
        ▼
引擎层    SPSS Python3 XD 持久会话（StartSPSS / Submit）
        ▼
输出层    OMS TEXT → Markdown/JSON ｜ HTML → PNG/TIFF ｜ DOCX → EMF
        ▼
IBM SPSS Statistics（本机授权；macOS 或 Windows）

文档

• 快速开始
• Agent 使用教程
• 样例数据与归档图
• 技术报告
• 结果解析
• 安全层
• 更新日志

致谢与许可证

• 上游：flupke91/spss-studio-mcp（MIT）
• 更早上游：Exekiel179/SPSS-MCP（MIT）
• 本仓库同样以 MIT 发布