spss-studio-mcp
This server lets AI agents use IBM SPSS Statistics on macOS as a statistics engine and chart factory, with safe execution and structured results.
Run arbitrary SPSS syntax and return Markdown/JSON structured results with statistical summaries
Perform common statistical analyses: t-tests, ANOVA, regression, logistic/ordinal regression, GLM, mixed models, correlations, factor analysis, reliability, nonparametric tests, MANOVA, survival analysis (Cox, Kaplan-Meier), discriminant analysis, clustering
Run mediation and moderation analyses (Baron & Kenny + Sobel test; mean-centred interaction regression)
Export publication-ready charts as 300-dpi PNG/TIFF (histograms, scatter, bar, line, boxplot, error bar, Q-Q plot, KM curve, area, density, bar with error)
Read, inspect, summarize, and convert SPSS .sav files without needing SPSS installed (list files/variables, metadata, data preview, file summary, CSV import)
Validate syntax safely with dry-run mode, dangerous-command blocking, directories allowlist, audit logging, and status checks
Discover registry-backed methods and inspect their schemas/support metadata
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 Run an independent-samples t-test on experiment_study.sav (grouping: group, dependent: posttest)"
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 for Mac
Make SPSS an Agent's "statistics engine + chart factory": paper-ready charts, deep result parsing, verified methods, and safe execution.
This MCP is Mac Only, for Windows versions, see flupke91/spss-studio-mcp.
English | 繁體中文(香港)
spss-studio-mcp is an MCP (Model Context Protocol) server for IBM SPSS
Statistics. It gives Agent clients such as Codex / Claude Code / Cursor:
Paper-ready charts: 11
spss_chart_*tools export PNG / TIFF (1950×1500 @300 dpi) in one call and return the file path for direct submission to journals;Deep result parsing: OMS text → Markdown tables + structured JSON + statistical summaries for 16 analysis families (t / F / r / B / Wald / α / χ² / p / effect sizes);
Verified methods: all 37 analysis tools plus 11 supporting tools are verified on real SPSS Statistics 32 for Mac;
Mediation / moderation:
spss_mediation(Baron & Kenny three-step regression + Sobel test) andspss_moderation(mean-centred interaction regression);Safety layer: dangerous-command blocking, data path allowlist,
dry_runpreflight, and JSONL audit logging.
Everything is verified on IBM SPSS Statistics 32.0.0.0 for macOS — 105 unit tests pass, including a self-contained real-machine reproduction manifest. Per-case results: docs/macos_verification.md.
Installation
Requirements: macOS · Python 3.10+ · IBM SPSS Statistics for Mac.
SPSS 32.0.0.0 is verified and auto-detected under /Applications; without it
only the file-reading tools work.
git clone https://github.com/CongJyu/spss-studio-mcp.git
cd spss-studio-mcp
bash scripts/install_macos.sh # .venv + deps + status + Claude Code config
bash scripts/install_macos.sh --codex # same, but writes the Codex config
bash scripts/install_macos.sh --local # Claude Code → ~/.claude/settings.local.jsonThe installer creates .venv, installs -e ".[dev]", runs a status check, and
writes the MCP client config.
1. Verify
.venv/bin/spss-studio-mcp status
# pyreadstat : OK v1.3.6
# pandas : OK v3.0.5
# SPSS batch : OK - /Applications/IBM SPSS Statistics/IBM SPSS Statistics.app/Contents/bin/spssengineSPSS batch : NOT FOUND means auto-detection failed — set SPSS_INSTALL_PATH
(see below and docs/macos_verification.md).
2. Configure your client
Client | Command | Written to |
Claude Code |
|
|
Codex |
|
|
Other MCP hosts |
| prints a JSON snippet to paste manually |
Both commands merge into the existing file and leave a timestamped backup
(*.backup.YYYYMMDD_HHMMSS). configure-claude --local targets
~/.claude/settings.local.json instead. Restart the client, then ask it to
run spss_check_status to confirm the server is connected.
Manual MCP configuration
The installer symlinks spss-studio-mcp into ~/.local/bin, so the plain
command name resolves in any client. Copy the matching snippet below — no path
editing needed.
If you passed
--no-link, or~/.local/binis not on yourPATH, substitute the absolute path to your clone (/absolute/path/to/spss-studio-mcp/.venv/bin/spss-studio-mcp).
Claude Code — ~/.claude.json, or .mcp.json at a project root:
{
"mcpServers": {
"spss": {
"type": "stdio",
"command": "spss-studio-mcp",
"args": ["serve", "--transport", "stdio"]
}
}
}Codex — ~/.codex/config.toml. This file is TOML, not JSON:
[mcp_servers.spss]
command = "spss-studio-mcp"
args = ["serve", "--transport", "stdio"]Codex aborts a tool call after 60 s by default. Add tool_timeout_sec = 600
inside the table if an analysis needs longer.
Gemini CLI — ~/.gemini/settings.json, or .gemini/settings.json at a
project root:
{
"mcpServers": {
"spss": {
"command": "spss-studio-mcp",
"args": ["serve", "--transport", "stdio"]
}
}
}Gemini CLI's default request timeout is 10 minutes, which already covers a full
analysis run, so no timeout key is needed.
If status reports SPSS batch : NOT FOUND, add the detection path to the
entry's env:
"env": {
"SPSS_INSTALL_PATH": "/Applications/IBM SPSS Statistics/IBM SPSS Statistics.app/Contents/bin"
}Restart the client after editing — MCP configuration is read at startup only.
Manual install
python3 -m venv .venv
.venv/bin/python -m pip install -e ".[dev]" # -e . for runtime only
.venv/bin/spss-studio-mcp configure-claude # or configure-codex / setup-infoEnvironment variables
Variable | Default | Purpose |
| auto-detected | SPSS |
|
| Per-analysis timeout, seconds |
|
| Engine startup timeout; licensing and Python init can be slow |
|
| Set to |
| — |
|
|
| Audit log path |
Full walkthrough: docs/tutorial.md.
Related MCP server: statlab-mcp
Paper-Ready Charts (Core Feature)
Tool | Purpose |
| Histogram / histogram with normal density |
| Scatter plot of two variables |
| Bar chart of category means / with 95% CI error bars |
| Time-series line / area charts |
| Grouped box-and-whisker plot |
| Mean ± CI error bar chart |
| Normal Q-Q plot |
| Kaplan-Meier survival curve |
spss_chart_histogram_density(
variable="engagement_total",
title="Engagement total distribution (with normal density)",
image_format="PNG", # PNG / TIFF
width_px=1950, height_px=1500, dpi=300,
data_file="examples/data/survey_study.sav",
)
# → returns the image file path, ready for submissionFormat note: chart output is PNG and TIFF only. Windows vector EMF export was removed because SPSS for macOS cannot produce EMF metafiles (its
OMS FORMAT=DOCarchive contains only raster PNG wrapped in.eps). Useimage_format="PNG"or"TIFF".
Structured Results & Statistical Summaries
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}The Markdown returned by run_syntax ends with a ### Statistical Summary
block containing a plain-language conclusion plus key statistics.
Extraction details for the 16 analysis families: docs/result_parsing.md.
Sample Datasets
examples/data/ ships five research-style datasets (fixed random seeds,
fully reproducible):
File | Scenario | Key variables |
| Survey: 200 students' learning engagement |
|
| Experiment: 120 participants, pre/post memory training |
|
| Survival: 150 follow-up cases |
|
| Mediation: 300 employees |
|
| Longitudinal: 60 people, 3 waves |
|
Safe Execution
Dangerous commands (
HOST/ERASE/DELETE FILE, ...) are blocked at the start of a line;Data files must live under
examples/, the system temp dir, or a directory declared inSPSS_ALLOWED_DIRS;spss_run_syntax(..., dry_run=True)validates without executing;Audit logs are written to
logs/audit.jsonlby default (override withSPSS_AUDIT_LOG).
See docs/security.md.
Documentation
License
MIT (upstream: flupke91/spss-studio-mcp, MIT).
MIT (upstream: Exekiel179/SPSS-MCP, MIT).
Available Tools
51 toolsspss_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 AreaA
Export a publication-ready area chart (PNG/TIFF) 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 BarC
Export a publication-ready bar chart (PNG/TIFF) 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) via GGRAPH + OMS.
Inputs: value (required), category (required), ci, dpi, +7 more. Returns: result
spss_chart_boxplotSpss Chart BoxplotB
Export a publication-ready box-and-whisker plot (PNG/TIFF) 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): 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) 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 DensityA
Export a publication-ready histogram overlaid with a normal density curve (PNG/TIFF) 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) 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 LineC
Export a publication-ready line chart (PNG/TIFF) 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 QqplotB
Export a publication-ready normal Q-Q plot (PNG/TIFF) 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 ScatterB
Export a publication-ready scatter plot (PNG/TIFF) 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
Scored across 51 tools
Most tools target clearly distinct SPSS procedures, file operations, or chart types. A few pairs overlap in practice (spss_list_variables vs spss_read_metadata, spss_chart_histogram vs spss_chart_histogram_density, spss_chart_bar vs spss_chart_bar_error), but descriptions generally clarify the boundaries.
All tools use a consistent spss_ snake_case prefix, with chart tools grouped under spss_chart_*. The naming is uniform and predictable across file I/O, statistical procedures, and chart exports.
51 tools is excessive for agent selection and tool management. While SPSS is a broad domain, many tools could be consolidated, especially the 12 chart-export tools and the family of regression/GLM procedures.
The surface covers data discovery, metadata inspection, import, syntax execution, a wide range of statistical analyses, and chart exports. Dedicated data-manipulation tools (recode, compute, merge, select cases) are absent, but spss_run_syntax provides a workaround.
Maintenance
Related MCP Connectors
A statistical analyst in your AI chat: bring data and a question, get a citable, re-runnable report.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
SEO & marketing toolkit for AI agents: GA4, Search Console, AdSense, GTM, PageSpeed, Trends.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables 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.518MIT
- AlicenseAqualityBmaintenanceEnables 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.6927 PyPI1MIT
- AlicenseAqualityBmaintenanceEnables AI agents to invoke a local Stata installation, including a Windows Stata build under Wine on Linux and macOS, for regression analysis, econometrics, paper replication, and empirical research with command guards, resource monitoring, and automatic log capture.42AGPL 3.0