Skip to main content
Glama
spss-studio-mcp

spss-studio-mcp

by CongJyu

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 | 繁體中文(香港)

License: MIT Python Tests

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) and spss_moderation (mean-centred interaction regression);

  • Safety layer: dangerous-command blocking, data path allowlist, dry_run preflight, 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.json

The 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/spssengine

SPSS 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

.venv/bin/spss-studio-mcp configure-claude

~/.claude.json → mcpServers.spss

Codex

.venv/bin/spss-studio-mcp configure-codex

~/.codex/config.toml → [mcp_servers.spss]

Other MCP hosts

.venv/bin/spss-studio-mcp setup-info

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/bin is not on your PATH, 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-info

Environment variables

Variable

Default

Purpose

SPSS_INSTALL_PATH

auto-detected

SPSS .app bundle, Contents/bin, or the spssengine binary — set only if detection fails

SPSS_TIMEOUT

120

Per-analysis timeout, seconds

SPSS_STARTUP_TIMEOUT

300

Engine startup timeout; licensing and Python init can be slow

SPSS_NO_SPSS

0

Set to 1 to force file-only mode

SPSS_ALLOWED_DIRS

—

;-separated extra directories allowed as data sources

SPSS_AUDIT_LOG

logs/audit.jsonl

Audit log path

Full walkthrough: docs/tutorial.md.

Related MCP server: statlab-mcp

Paper-Ready Charts (Core Feature)

Tool

Purpose

spss_chart_histogram / spss_chart_histogram_density

Histogram / histogram with normal density

spss_chart_scatter

Scatter plot of two variables

spss_chart_bar / spss_chart_bar_error

Bar chart of category means / with 95% CI error bars

spss_chart_line / spss_chart_area

Time-series line / area charts

spss_chart_boxplot

Grouped box-and-whisker plot

spss_chart_errorbar

Mean ± CI error bar chart

spss_chart_qqplot

Normal Q-Q plot

spss_chart_km_curve

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 submission

Format 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=DOC archive contains only raster PNG wrapped in .eps). Use image_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_study.sav

Survey: 200 students' learning engagement

gender / major / q1–q12 / engagement_total

experiment_study.sav

Experiment: 120 participants, pre/post memory training

group / pretest / posttest / gain

survival_study.sav

Survival: 150 follow-up cases

treatment / time / status

mediation_study.sav

Mediation: 300 employees

autonomy / satisfaction / performance

longitudinal_study.sav / long_study.sav

Longitudinal: 60 people, 3 waves

id / group / time / score

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 in SPSS_ALLOWED_DIRS;

  • spss_run_syntax(..., dry_run=True) validates without executing;

  • Audit logs are written to logs/audit.jsonl by default (override with SPSS_AUDIT_LOG).

See docs/security.md.

Documentation

License

MIT (upstream: flupke91/spss-studio-mcp, MIT).

MIT (upstream: Exekiel179/SPSS-MCP, MIT).

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

    B3.2/5.0

    Scored across 51 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count2/5

    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.

    Completeness4/5

    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

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • 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.
      51
      8
      MIT
    • A
      license
      A
      quality
      B
      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
      A
      quality
      B
      maintenance
      Enables 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.
      4
      2
      AGPL 3.0