Skip to main content
Glama
spss-studio-mcp

spss-studio-mcp

by flupke91

SPSS Studio MCP

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

简体中文 | English

License: MIT Python CI Release

spss-studio-mcp 是一个面向 IBM SPSS Statistics 的 MCP(Model Context Protocol)服务器,为 Codex / Claude Code / Cursor 等 Agent 客户端提供:

  • 论文级出图:11 类 spss_chart_* 工具,一键导出 PNG / TIFF / EMF(1950×1500 @300 dpi),路径回传可直接投稿;

  • 深度结果解析:OMS 文本 → Markdown 表格 + 结构化 JSON + 16 类分析统计摘要(t / F / r / B / Wald / α / χ² / p / 效应量);

  • 方法真机验证:37 个分析方法 + 11 个补充工具全部在真实 SPSS 32 验收通过;

  • 中介 / 调节:spss_mediation(Baron & Kenny 三步回归 + Sobel)、spss_moderation(中心化交互回归);

  • 安全执行层:危险命令拦截、数据路径白名单、dry_run 预检、JSONL 审计日志。

全部能力已在 IBM SPSS Statistics 32.0.0(Windows) 真机验证(109 个单元测试全部通过)。


系统架构

SPSS Studio MCP 架构图

MCP 客户端(Codex / Claude Code / Cursor)
        │  MCP 协议(stdio)
        ▼
工具层    60+ 工具:文件/元数据 · 37+ 分析方法 · 11 类图表 · 中介/调节 · 结构化结果
        ▼
语法构建   方法模板 + Pydantic 校验 | 安全层(危险拦截 / 白名单 / dry_run / 审计)
        ▼
引擎层    SPSS Python3 XD API 持久会话(spss.StartSPSS / spss.Submit)
        ▼
输出层    OMS TEXT→Markdown+JSON 摘要 | OMS HTML→PNG/TIFF | OMS DOCX→EMF
        ▼
IBM SPSS Statistics 32.0.0(Windows,本地授权)

架构源文件(draw.io 可编辑):docs/diagrams/architecture.drawio

Related MCP server: SPSS-MCP Extended

快速开始

cd spss-studio-mcp
pip install -e ".[dev]"
spss-studio-mcp status                     # 应显示 SPSS batch: OK

spss-studio-mcp configure-codex            # 写入 Codex 客户端配置(~/.codex/config.toml)
spss-studio-mcp configure-claude           # 写入 Claude Code 配置(~/.claude.json)

然后在客户端里直接用自然语言驱动,例如:

对 examples/data/survey_study.sav 做描述统计和可靠性分析
用 examples/data/experiment_study.sav 做独立样本 t 检验(group 分组,posttest)
用 examples/data/mediation_study.sav 做中介分析:autonomy → satisfaction → performance
画 examples/data/survey_study.sav 学习投入总分的直方图(带正态密度),PNG 300dpi

论文级图表(核心卖点)

工具

用途

spss_chart_histogram / spss_chart_histogram_density

分布直方图 / 直方图 + 正态密度

spss_chart_scatter

两变量散点图

spss_chart_bar / spss_chart_bar_error

分类均值条形 / 条形 + 95% CI 误差须

spss_chart_line / spss_chart_area

时间序列折线 / 面积图

spss_chart_boxplot

分组箱线图

spss_chart_errorbar

均值 ± CI 误差条

spss_chart_qqplot

正态 Q-Q 图

spss_chart_km_curve

Kaplan-Meier 生存曲线

spss_chart_histogram_density(
    variable="engagement_total",
    title="学习投入总分分布(带正态密度)",
    image_format="PNG",            # PNG / TIFF / EMF
    width_px=1950, height_px=1500, dpi=300,
    data_file="examples/data/survey_study.sav",
)
# → 返回图片文件路径,可直接投稿

样例输出(SPSS 32 真机导出,1950×1500 @300 dpi):

学习投入总分直方图(带正态密度) 不同专业学习投入总分(均值 + 95% CI) 实验后测成绩箱线图 按治疗分组的 KM 生存曲线 满意度与绩效散点图

结构化结果与统计摘要

spss_structured_result(
    syntax="T-TEST GROUPS=group(1 2) /VARIABLES=posttest.",
    data_file="examples/data/experiment_study.sav",
)
# → {markdown, json: {tables, summary}, files, warnings}

run_syntax 返回的 Markdown 末尾自动附加 ### 统计摘要(自然语言结论 + 关键统计量), 16 类分析的摘要抽取细节见 docs/result_parsing.md。

样例数据

examples/data/ 提供 5 组贴近论文场景的样例数据(固定随机种子,可复现):

文件

场景

关键变量

survey_study.sav

问卷:200 人学习投入

gender / major / q1–q12 / engagement_total

experiment_study.sav

实验:120 人记忆训练前后测

group / pretest / posttest / gain

survival_study.sav

生存:150 例随访

treatment / time / status

mediation_study.sav

中介:300 员工

autonomy / satisfaction / performance

longitudinal_study.sav / long_study.sav

纵向:60 人 3 次测量

id / group / time / score

安全执行

  • 危险命令(HOST / ERASE / DELETE FILE 等)行首匹配拦截;

  • 数据文件路径白名单(SPSS_ALLOWED_DIRS,默认 examples/ + 系统临时目录);

  • spss_run_syntax(..., dry_run=True) 先校验不执行;

  • 审计日志默认写入 logs/audit.jsonl(可用 SPSS_AUDIT_LOG 改路径)。

详见 docs/security.md。

文档

生态收录与发布

许可证

MIT(上游:Exekiel179/SPSS-MCP,MIT)。

Available Tools

51 tools
spss_anovaB

Run SPSS one-way ANOVA (ONEWAY). Optionally includes post-hoc tests (e.g., TUKEY, BONFERRONI, LSD). Requires IBM SPSS Statistics to be installed.

Inputs: factor (required), dependent (required), file_path (required), post_hoc. Returns: result

spss_chart_areaA

Export a publication-ready area chart (PNG/TIFF/EMF) of y against a time/ordinal x variable, via GGRAPH + OMS.

Inputs: x (required), y (required), dpi, title, +6 more. Returns: result

spss_chart_barA

Export a publication-ready bar chart (PNG/TIFF/EMF) of a categorical variable against the mean (or sum) of a continuous variable, via GGRAPH + OMS IMAGE.

Inputs: value (required), category (required), dpi, stat, +7 more. Returns: result

spss_chart_bar_errorA

Export a publication-ready bar chart of category means with confidence-interval error bars (PNG/TIFF/EMF) via GGRAPH + OMS.

Inputs: value (required), category (required), ci, dpi, +7 more. Returns: result

spss_chart_boxplotB

Export a publication-ready box-and-whisker plot (PNG/TIFF/EMF) via GGRAPH + OMS. Provide a continuous variable and optionally a categorical grouping variable.

Inputs: variable (required), dpi, title, x_label, +6 more. Returns: result

spss_chart_errorbarB

Export a publication-ready error bar chart (PNG/TIFF/EMF): mean with confidence-interval whiskers per category, via GGRAPH + OMS.

Inputs: value (required), category (required), ci, dpi, +7 more. Returns: result

spss_chart_histogramB

Export a publication-ready histogram (PNG/TIFF/EMF) via GGRAPH + OMS IMAGE. Provide the continuous variable; the chart file path is returned for direct submission.

Inputs: variable (required), dpi, title, x_label, +5 more. Returns: result

spss_chart_histogram_densityA

Export a publication-ready histogram overlaid with a normal density curve (PNG/TIFF/EMF) via GGRAPH + OMS. Provide a continuous variable.

Inputs: variable (required), dpi, title, x_label, +5 more. Returns: result

spss_chart_km_curveB

Export a publication-ready Kaplan-Meier survival curve (PNG/TIFF/EMF) via the KM procedure. Provide time and status variables; group is optional.

Inputs: time (required), status (required), dpi, event, +6 more. Returns: result

spss_chart_lineA

Export a publication-ready line chart (PNG/TIFF/EMF) via GGRAPH + OMS IMAGE. Provide the x (time/ordinal) and y variables; the file path is returned.

Inputs: x (required), y (required), dpi, title, +6 more. Returns: result

spss_chart_qqplotB

Export a publication-ready normal Q-Q plot (PNG/TIFF/EMF) of a continuous variable via PPLOT, captured through the OMS chart pipeline.

Inputs: variable (required), dpi, title, width_px, +3 more. Returns: result

spss_chart_scatterA

Export a publication-ready scatter plot (PNG/TIFF/EMF) via GGRAPH + OMS IMAGE. Provide x and y variables; the chart file path is returned for direct submission.

Inputs: x (required), y (required), dpi, title, +6 more. Returns: result

spss_check_statusA

Check the SPSS MCP server status: which capabilities are available (SPSS installed vs file-only mode), SPSS path, library versions, and configuration. Call this first to understand what tools are available.

Inputs: no named parameters. Returns: result

spss_cluster_hierarchicalC

Run hierarchical cluster analysis with dendrogram. Supports multiple linkage methods and distance measures. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), variables (required), method, measure, +2 more. Returns: result

spss_compute_scale_scoreA

Compute a scale score (SUM or MEAN) from multiple item variables, with optional reverse coding and minimum valid item count. Requires IBM SPSS Statistics to be installed.

Inputs: items (required), file_path (required), new_variable (required), method, +4 more. Returns: result

spss_correlationsB

Run SPSS CORRELATIONS to compute Pearson or Spearman correlation matrix. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), variables (required), method, two_tailed. Returns: result

spss_cox_regressionB

Run Cox proportional hazards regression for survival analysis. Supports time-dependent covariates, stratification, and model diagnostics. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), predictors (required), time_variable (required), status_variable (required), +5 more. Returns: result

spss_crosstabsA

Run SPSS CROSSTABS to create a contingency table between two categorical variables. Optionally includes chi-square test and row/column percentages. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), row_variable (required), column_variable (required), include_col_pct, +2 more. Returns: result

spss_descriptivesB

Run SPSS DESCRIPTIVES for numeric variables. Returns N, mean, std deviation, min, max, and optional statistics. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), variables (required), statistics. Returns: result

spss_discriminantA

Run discriminant analysis to classify cases into groups. Supports stepwise selection and cross-validation. Requires IBM SPSS Statistics to be installed.

Inputs: groups (required), file_path (required), predictors (required), method, +4 more. Returns: result

spss_factorA

Run SPSS FACTOR analysis (principal components or principal axis factoring). Includes eigenvalues, variance explained, and rotated factor matrix. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), variables (required), method, rotation, +1 more. Returns: result

spss_file_summaryA

Get a summary of an SPSS .sav file: case count, variable count, variable list, and basic descriptive statistics computed locally (no SPSS needed). Does not require SPSS to be installed.

Inputs: file_path (required). Returns: result

spss_frequenciesA

Run SPSS FREQUENCIES on one or more variables. Returns frequency tables with counts, percentages, and optional statistics. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), variables (required), statistics. Returns: result

spss_genlinC

Run generalized linear model (GENLIN) with flexible distribution and link functions. Supports Poisson, binomial, gamma, negative binomial, and other distributions. Requires IBM SPSS Statistics to be installed.

Inputs: dependent (required), file_path (required), predictors (required), link, +4 more. Returns: result

spss_genlinmixedB

Run generalized linear mixed model combining GLM with random effects. Supports non-normal outcomes with hierarchical structure. Requires IBM SPSS Statistics to be installed.

Inputs: dependent (required), file_path (required), fixed_effects (required), link, +3 more. Returns: result

spss_get_method_schemaA

Get the JSON schema for a registry-backed SPSS method. Useful for structured orchestration and parameter inspection before execution.

Inputs: tool_name (required). Returns: result

spss_get_method_supportA

Get support metadata for a registry-backed SPSS method, including command family, support tier, coverage assertions, and documentation tags.

Inputs: tool_name (required). Returns: result

spss_glm_univariateB

Run univariate general linear model (GLM) with factorial designs. Supports estimated marginal means, contrasts, and post-hoc tests. Requires IBM SPSS Statistics to be installed.

Inputs: factors (required), dependent (required), file_path (required), emmeans, +4 more. Returns: result

spss_import_csvA

Convert a CSV file to SPSS .sav format directly using pandas + pyreadstat — no IBM SPSS Statistics installation required. Much faster than going through SPSS syntax because it bypasses the SPSS engine entirely. Saves the .sav file next to the CSV by default, or to a custom output_path.

Inputs: csv_path (required), encoding, delimiter, output_path, +1 more. Returns: result

spss_kaplan_meierA

Run Kaplan-Meier survival analysis with log-rank test. Produces survival curves and compares groups. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), time_variable (required), status_variable (required), status_event_value (required), +3 more. Returns: result

spss_list_filesA

List SPSS .sav files in a directory. Useful for discovering available datasets when the user hasn't specified a file path.

Inputs: directory (required), recursive. Returns: result

spss_list_supported_methodsA

List registry-backed SPSS methods available for structured execution. Use this to discover cold methods that have schemas, templates, and coverage assertions.

Inputs: no named parameters. Returns: result

spss_list_variablesA

List all variable names and their labels from an SPSS .sav file. Optionally filter by a search term. Does not require SPSS to be installed.

Inputs: file_path (required), search. Returns: result

spss_logistic_regressionB

Run binary or multinomial logistic regression. Supports stepwise selection, categorical predictors, and model diagnostics. Requires IBM SPSS Statistics to be installed.

Inputs: dependent (required), file_path (required), predictors (required), method, +4 more. Returns: result

spss_manovaA

Run multivariate analysis of variance (MANOVA) for multiple dependent variables. Tests multivariate effects and provides univariate follow-ups. Requires IBM SPSS Statistics to be installed.

Inputs: factors (required), file_path (required), dependents (required), method, +4 more. Returns: result

spss_mediationA

Run a Baron & Kenny three-step mediation analysis (X -> M -> Y) with regression, reporting paths a/b/c/c', the indirect effect a*b, and a Sobel test. Does not bundle the PROCESS macro.

Inputs: x (required), y (required), mediator (required), file_path (required). Returns: result

spss_mixedC

Run linear mixed-effects model (multilevel model) with random effects. Supports nested and crossed random effects, repeated measures structures. Requires IBM SPSS Statistics to be installed.

Inputs: dependent (required), file_path (required), fixed_effects (required), method, +5 more. Returns: result

spss_moderationA

Run a mean-centred moderation regression (Y ~ X + W + X*W) and report the interaction term that tests the moderating effect of W.

Inputs: x (required), y (required), file_path (required), moderator (required). Returns: result

spss_nonparametric_testsC

Run common nonparametric tests in SPSS: Mann-Whitney U, Wilcoxon signed-rank, or Kruskal-Wallis. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), test_type (required), variables (required), group_values, +1 more. Returns: result

spss_normality_outliersA

Run SPSS EXAMINE to check normality and outliers for numeric variables, with optional diagnostic plots. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), variables (required), plots. Returns: result

spss_ordinal_regressionB

Run ordinal regression (PLUM) for ordered categorical outcomes. Supports multiple link functions and parallel lines test. Requires IBM SPSS Statistics to be installed.

Inputs: dependent (required), file_path (required), predictors (required), link, +3 more. Returns: result

spss_read_dataA

Read rows of data from an SPSS .sav file as a Markdown table. Optionally filter to specific variables and limit row count. Does not require SPSS to be installed.

Inputs: file_path (required), max_rows, variables, apply_value_labels. Returns: result

spss_read_metadataA

Read variable names, types, labels, and value labels from an SPSS .sav file. Returns a detailed Markdown report of the file's structure. Does not require SPSS to be installed.

Inputs: file_path (required). Returns: result

spss_regressionA

Run SPSS linear regression. Specify a dependent variable and one or more predictors. Returns coefficients, R-squared, ANOVA table, and significance tests. Requires IBM SPSS Statistics to be installed.

Inputs: dependent (required), file_path (required), predictors (required), method, +1 more. Returns: result

spss_reliability_alphaA

Run SPSS RELIABILITY analysis (Cronbach's alpha). Returns scale reliability and item statistics for psychometric workflows. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), variables (required), model, scale_name. Returns: result

spss_repeated_measures_anovaA

Run SPSS repeated-measures ANOVA (within-subject GLM). Provide within-factor name, number of levels, and one variable per level. Requires IBM SPSS Statistics to be installed.

Inputs: levels (required), file_path (required), variables (required), within_factor_name (required), +1 more. Returns: result

spss_run_syntaxA

Execute arbitrary SPSS syntax commands and return the output as Markdown. Optionally specify a data_file to automatically prepend GET FILE. By default, this also persists .spv (SPSS viewer) and .sps (executed syntax) files. Requires IBM SPSS Statistics to be installed.

Inputs: syntax (required), dry_run, data_file, select_if, +3 more. Returns: result

spss_structured_resultC

Run SPSS syntax and return a unified structured result as JSON: {markdown, json: {tables, summary}, files, warnings}. The summary extracts key statistics (t/F/r/B/p) for t-test, ANOVA, correlation, regression, descriptives and frequencies.

Inputs: syntax (required), data_file, select_if, filter_variable, +2 more. Returns: result

spss_t_testB

Run SPSS t-test. Supports one_sample, independent, and paired test types. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), test_type (required), variables (required), test_value, +1 more. Returns: result

spss_twostep_clusterA

Run two-step cluster analysis with automatic cluster number determination. Handles large datasets and mixed variable types. Requires IBM SPSS Statistics to be installed.

Inputs: file_path (required), distance, continuous, categorical, +3 more. Returns: result

spss_validate_syntaxA

Validate SPSS syntax without executing it. Checks for basic syntax errors. Requires IBM SPSS Statistics to be installed.

Inputs: syntax (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 51 tools

    Disambiguation4/5

    Most tools correspond to distinct SPSS procedures (e.g., frequencies, crosstabs, t_test), but some overlap in purpose exists within the GLM family (spss_anova, spss_glm_univariate, spss_manova, spss_repeated_measures_anova) and between spss_kaplan_meier and spss_cox_regression. Chart tools are clearly differentiated by chart type, but the high number of similar analytic procedures could cause occasional misselection.

    Naming Consistency5/5

    All tools share the spss_ prefix. Most use a predictable spss_<procedure> pattern for statistical analyses and spss_chart_<type> for charts, with file/utility tools using verb_noun (spss_list_files, spss_read_metadata). The set is internally consistent and easy to navigate.

    Tool Count3/5

    At 51 tools, the server is heavily oversized for most use cases, but the scope of an SPSS integration genuinely requires many procedures, charts, and file operations. The count is justified yet borderline, as it may overwhelm agents and slow tool selection.

    Completeness4/5

    The server covers broad SPSS workflows: data loading/reading, descriptive statistics, common tests, advanced models (logistic, mixed, survival), charts, and syntax execution. Minor gaps exist, such as no dedicated data transformation/recoding tool beyond scale scoring, though spss_run_syntax covers arbitrary operations.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to perform reproducible, verifiable statistical analysis through 25 deterministic tools for descriptive statistics, hypothesis testing, regression, clustering, time-series forecasting, and Chinese-labeled plotting.
      30
      1
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to run IBM SPSS Statistics on macOS for statistical analyses, generate paper-ready charts, extract structured results, and execute mediation/moderation analyses with safety controls.
      51
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Enables AI agents to safely execute statistical analyses, parse results into Markdown and JSON, and generate publication-ready charts through a local IBM SPSS Statistics installation on macOS and Windows.
      51
      62 PyPI
      MIT