Skip to main content
Glama
SPSS Studio MCP

SPSS Studio MCP

by kinginsun

spss-mcp (macOS + Windows)

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

简体中文 | English

License: MIT PyPI Python Platform

面向 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)

Related MCP server: spss-studio-mcp

本 fork 相对上游的主要改动

项

说明

macOS 探测

自动发现 /Applications/IBM SPSS Statistics *

XD 启动

设置 SPSS_HOME、DYLD_*,修复捆绑 libpython 加载

出图

macOS HTML 内嵌 JPEG → 自动转 PNG,再缩放至 300 dpi

路径

相对路径解析为绝对路径,避免 SPSS Error #61

解析

避免把 ANOVA 表中的 Error SS 误判为 Error #

样例数据

宽表 / 长表纵向数据对齐,便于 RM-ANOVA 与 MIXED

系统要求

  • 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)

文档

致谢与许可证

Available Tools

51 tools
spss_anovaSpss 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_areaSpss Chart AreaB

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_barSpss Chart BarB

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_errorSpss Chart Bar ErrorC

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_boxplotSpss Chart BoxplotC

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_errorbarSpss Chart ErrorbarC

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_histogramSpss Chart HistogramC

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_densitySpss Chart Histogram DensityB

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_curveSpss Chart Km CurveC

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_lineSpss Chart LineB

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_qqplotSpss Chart QqplotA

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_scatterSpss Chart ScatterC

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_statusSpss 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_hierarchicalSpss 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_scoreSpss Compute Scale ScoreC

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_correlationsSpss CorrelationsC

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_regressionSpss Cox RegressionC

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_crosstabsSpss 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_descriptivesSpss 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_discriminantSpss DiscriminantC

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_factorSpss FactorC

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_summarySpss 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_frequenciesSpss FrequenciesB

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_genlinSpss 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_genlinmixedSpss GenlinmixedC

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_schemaSpss 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_supportSpss Get Method SupportB

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_univariateSpss 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_csvSpss 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_meierSpss Kaplan MeierC

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_filesSpss List FilesB

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_methodsSpss 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_variablesSpss List VariablesB

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_regressionSpss 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_manovaSpss ManovaC

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_mediationSpss 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_mixedSpss 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_moderationSpss 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_testsSpss 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_outliersSpss 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_regressionSpss 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_dataSpss Read DataB

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_metadataSpss Read MetadataB

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_regressionSpss RegressionB

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_alphaSpss Reliability AlphaC

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_anovaSpss Repeated Measures AnovaB

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_syntaxSpss Run SyntaxB

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_resultSpss 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_testSpss T TestC

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_clusterSpss Twostep ClusterB

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_syntaxSpss 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

    B3/5.0

    Scored across 51 tools

    Disambiguation3/5

    Most statistical procedures are distinct, but there is notable overlap among execution/meta tools (spss_run_syntax, spss_structured_result, spss_validate_syntax), file inspection tools (spss_list_variables, spss_read_metadata, spss_file_summary), and chart variants (spss_chart_histogram vs spss_chart_histogram_density, spss_chart_bar vs spss_chart_bar_error). Descriptions help, but with 51 tools an agent faces real misselection risk.

    Naming Consistency4/5

    All tools use the spss_ prefix, lowercase snake_case, and descriptive names; chart tools consistently follow spss_chart_<type>. Some names are procedure nouns (spss_anova, spss_correlations) while others use verb phrases (spss_run_syntax, spss_get_method_schema), so it is not a strict verb_noun pattern.

    Tool Count2/5

    51 tools far exceed the typical 3-15 ergonomic range and create a heavy selection burden. The statistical breadth justifies many distinct procedures, but chart variants, registry meta-tools, and overlapping file readers could be consolidated behind fewer tools.

    Completeness4/5

    The surface covers data discovery/reading, syntax execution, a broad statistical procedure library, chart export, structured results, and mediation/moderation, so most analysis workflows are supported. Gaps remain in data manipulation and export (recode, merge, save/export) and some specialist procedures, though spss_run_syntax provides a workaround.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Connects AI agents to a local Stata installation, enabling execution of Stata code, data inspection, graph generation, and result verification through natural language interactions.
      1,054 PyPI
      92
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to drive IBM SPSS Statistics for statistical analysis and publication-quality chart generation through natural language, returning structured results and ensuring safe execution.
      2
      51
      9
      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