spss-studio-mcp
spss-studio-mcp is an MCP server that lets agents inspect SPSS data, run statistical analyses, generate publication-ready charts, and parse SPSS results safely.
Inspect
.savfiles: list variables, read metadata/data, summarize files, and discover datasets without SPSS installed.Convert CSV files to
.savusing pandas/pyreadstat, no SPSS engine required.Check server/SPSS status and discover registry-backed method schemas and support metadata.
Execute or validate arbitrary SPSS syntax, with optional
dry_runprechecks.Run core statistics: descriptives, frequencies, crosstabs, t-tests, ANOVA, correlations, regression, logistic/ordinal regression, factor analysis, reliability alpha, scale scoring, nonparametric tests, normality/outlier checks.
Run advanced models: repeated-measures ANOVA, GLM/MANOVA, mixed models, GENLIN/GENLINMIXED, Cox regression, Kaplan-Meier, discriminant analysis, hierarchical/two-step clustering.
Run mediation (Baron & Kenny + Sobel) and moderation (centered interaction regression).
Export publication-ready charts as PNG/TIFF/EMF at 1950x1500 @300 dpi: histogram, histogram+density, scatter, bar, bar+error, line, area, boxplot, errorbar, Q-Q, and KM curve.
Return Markdown tables plus structured JSON summaries with key statistics and warnings.
Enforce safety features: dangerous command blocking, path allowlists, dry runs, and JSONL audit logging.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@spss-studio-mcp 用 examples/data/survey_study.sav 做描述统计和可靠性分析"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
SPSS Studio MCP
让 SPSS 成为 Agent 的「统计引擎 + 制图工厂」:论文级图片、深度结果解析、方法真机验证、安全执行。
简体中文 | English
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 个单元测试全部通过)。
系统架构

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论文级图表(核心卖点)
工具 | 用途 |
| 分布直方图 / 直方图 + 正态密度 |
| 两变量散点图 |
| 分类均值条形 / 条形 + 95% CI 误差须 |
| 时间序列折线 / 面积图 |
| 分组箱线图 |
| 均值 ± CI 误差条 |
| 正态 Q-Q 图 |
| 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):

结构化结果与统计摘要
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 组贴近论文场景的样例数据(固定随机种子,可复现):
文件 | 场景 | 关键变量 |
| 问卷:200 人学习投入 |
|
| 实验:120 人记忆训练前后测 |
|
| 生存:150 例随访 |
|
| 中介:300 员工 |
|
| 纵向:60 人 3 次测量 |
|
安全执行
危险命令(
HOST/ERASE/DELETE FILE等)行首匹配拦截;数据文件路径白名单(
SPSS_ALLOWED_DIRS,默认examples/+ 系统临时目录);spss_run_syntax(..., dry_run=True)先校验不执行;审计日志默认写入
logs/audit.jsonl(可用SPSS_AUDIT_LOG改路径)。
详见 docs/security.md。
文档
Agent 傻瓜式使用教程:包含一键安装 Prompt、Codex/Claude Code 配置、论文分析场景和故障排查
生态收录与发布
状态:P0–P4 里程碑完成,v1.0.0 已发布(GitHub Releases);
LobeHub / PulseMCP 收录条目与提交清单:docs/ecosystem.md;
Release v1.0.0 说明:docs/release_notes_v1.0.md。
许可证
MIT(上游:Exekiel179/SPSS-MCP,MIT)。
Available Tools
51 toolsspss_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
Scored across 51 tools
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.
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.
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.
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
Related MCP Connectors
A statistical analyst in your AI chat: bring data and a question, get a citable, re-runnable report.
Ask questions of SPSS .sav survey data: crosstabs with significance, and AI coding of open ends.
Clean messy tabular data and render publication-ready PNG charts from your AI assistant.
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables 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.301MIT
- AlicenseBqualityBmaintenanceEnables AI assistants to execute IBM SPSS Statistics workflows via natural language, covering data management, restructuring, analysis, charting, and report export.6936 PyPI1MIT
- AlicenseBqualityBmaintenanceEnables 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.51MIT
- AlicenseBqualityBmaintenanceEnables 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.5162 PyPIMIT