SPSS-MCP Extended

A Model Context Protocol (MCP) server that gives AI assistants direct access to IBM SPSS Statistics — covering the full research pipeline from data preparation to reporting.

Describe your analysis in plain language — SPSS-MCP translates it into SPSS syntax, runs it against the real SPSS engine, and returns Markdown-formatted results.

v2.0 — 69 tools, 100% live-tested on IBM SPSS Statistics 27.

---

What's New in v2.0

v2.0 substantially extends the original v0.3.0 analysis bridge (37 tools) into a complete workflow — data cleaning, transformation, merging, restructuring, analysis, charting, and export.

Metric	v0.3.0 base	v2.0
Total tools	37	69 (+32)
Data management (RECODE, COMPUTE, labels...)	0	14
Restructuring & merging (MATCH FILES, AGGREGATE, FLIP...)	0	8
Reporting, export & charts	0	6
Advanced procedures (K-means, ARIMA, PROXIMITIES...)	0	4
Live-verified tools	33/37 (89%)	69/69 (100%)
Syntax bugs fixed	—	16
SPSS command coverage	~26%	~85%

Key engineering improvements

• Auto factor/group range detection — MANOVA and DISCRIMINANT used to fail when (min,max) ranges were missing; now ranges are read from the data via pyreadstat. Works with zero configuration.
• Data-management success detection — commands like RECODE and SAVE produce no OMS tables; the runner now recognizes them and reports success correctly.
• Working output export — SPSS's OUTPUT EXPORT command requires a GUI Viewer that doesn't exist in batch mode (verified live). Export runs through OMS /DESTINATION instead, producing real DOC / XLS / HTML files.
• OMS flush-race protection — OMS destination files appear moments after job completion; the export tool polls before declaring failure.
• Verified syntax catalog — 57 SPSS commands extracted from IBM's 2,414-page Command Syntax Reference with page citations (SYNTAX_CATALOG.md), all templates battle-tested against live SPSS 27.

Syntax bugs fixed in v2.0 (16)

compute_scale_score (missing commas in MEAN()), genlin (/PRINT= invalid), genlinmixed (nonexistent /PRINT subcommand + missing terminator), manova (missing factor ranges), discriminant (missing group range), twostep_cluster (invalid /DISTANCE=EUCLID), ordinal_regression (nonexistent /TEST=PARALLEL), correlations (invalid /PRINT=TAILS(2)), factor (wrong /CRITERIA order, no PCA method), nonparametric_tests (missing value pairs), cluster_hierarchical (bare terminator), plus 5 more found during v2.0 development — see TEST_REPORT.md for the complete audit trail.

---

Requirements

• Windows 10/11
• Python 3.10+
• IBM SPSS Statistics (version 20–31)
• Claude Code (or any MCP client) with MCP support

---

Quick Install

From PyPI (Recommended)

pip install spss-mcp-extended

# Auto-configure Claude Code
spss-mcp configure-claude

# Restart Claude Code

One-Click (from source)

git clone https://github.com/rasitnarcicek/spss-mcp-extended.git
cd spss-mcp-extended
install.bat

Then restart Claude Code. Done!

Manual Install (from source)

# 1. Install
pip install -e .

# 2. Auto-configure Claude Code
spss-mcp configure-claude

# 3. Restart Claude Code

---

Configuration

Basic Setup

Recommended: let SPSS-MCP auto-configure Claude Code for you:

spss-mcp configure-claude

This command:

• detects your SPSS installation
• merges mcpServers.spss into Claude Code's user config (~/.claude.json)
• creates a timestamped backup before updating existing settings

If you prefer manual setup, add this to Claude Code settings (Ctrl+, → search mcpServers):

{
  "mcpServers": {
    "spss": {
      "command": "spss-mcp",
      "args": ["serve", "--transport", "stdio"]
    }
  }
}

SPSS Path (if not auto-detected)

Create .env file (see .env.example):

SPSS_INSTALL_PATH=C:\Program Files\IBM\SPSS Statistics\27

Slow SPSS startup?

SPSS_STARTUP_TIMEOUT=300

This is separate from SPSS_TIMEOUT, which controls the per-job timeout after the engine is running.

Optional: Install Skills

Skills make analysis more reliable and auto-save results:

set SKILLS_DIR=%USERPROFILE%\.claude\skills
xcopy /E /I skills\spss-analyst "%SKILLS_DIR%\spss-analyst"
xcopy /E /I skills\spss-mcp-guard "%SKILLS_DIR%\spss-mcp-guard"

Restart Claude Code after installation.

---

Usage

Just describe your analysis in natural language:

Recode age into three groups: 18-30, 31-50, 51+ and save as new variable

Merge survey.sav and demographics.sav by respondent id

Compute BMI = weight/height^2, then test gender differences with t-test

Export all results to a Word document

Claude will:

1. Read your data file
2. Generate SPSS syntax
3. Execute the analysis
4. Return formatted results
5. Save .spv and .sps files

---

Output Files

Every analysis produces:

File	Description
.spv	SPSS Viewer file (open in SPSS for full charts)
.sps	SPSS syntax file (the exact commands that ran)
.doc/.xls/.html	Exported reports (via spss_export_output)

Default location: %TEMP%\spss-mcp\results\

---

Available Tools (69 total)

File & Data (10)

spss_check_status · spss_list_files · spss_list_variables · spss_read_metadata · spss_read_data · spss_file_summary · spss_import_csv · spss_list_supported_methods · spss_get_method_schema · spss_get_method_support

Basic Statistics (9)

spss_frequencies · spss_descriptives · spss_crosstabs · spss_t_test · spss_anova · spss_correlations · spss_regression · spss_normality_outliers · spss_nonparametric_tests

Advanced Analysis (13)

spss_factor · spss_reliability_alpha · spss_compute_scale_score · spss_repeated_measures_anova · spss_logistic_regression · spss_ordinal_regression · spss_genlin · spss_mixed · spss_genlinmixed · spss_cox_regression · spss_kaplan_meier · spss_manova · spss_glm_univariate

Clustering & Classification (3)

spss_discriminant · spss_cluster_hierarchical · spss_twostep_cluster

Data Management (14) — new in v2.0

spss_recode · spss_autorecode · spss_compute · spss_if_transform · spss_select_if · spss_sort_cases · spss_weight · spss_filter · spss_missing_values · spss_variable_labels · spss_value_labels · spss_formats · spss_declare_variables · spss_save_file

Restructuring & Merging (8) — new in v2.0

spss_match_files · spss_add_files · spss_star_join · spss_aggregate · spss_rank · spss_flip · spss_vars_to_cases · spss_cases_to_vars

Reporting & Charts (6) — new in v2.0

spss_export_output · spss_graph_scatter · spss_graph_histogram · spss_graph_boxplot · spss_graph_bar · spss_custom_tables

Advanced Procedures (4) — new in v2.0

spss_quick_cluster · spss_proximities · spss_arima · spss_ratio_statistics

Generic

spss_run_syntax — execute any raw SPSS syntax spss_validate_syntax — dry-run validation without execution

Full parameter reference: TOOLS_REFERENCE.md

---

Troubleshooting

SPSS not detected

Run spss-mcp status. If SPSS shows ✗:

1. Create .env file with SPSS path (see .env.example)
2. Restart Claude Code

Analysis timeout

SPSS_TIMEOUT=300

MCP server not connecting

1. Check JSON syntax in settings
2. Verify spss-mcp command works in terminal
3. Re-run spss-mcp configure-claude
4. Restart Claude Code

---

Platform Support

Platform	File Tools	Analysis Tools
Windows 10/11	✓	✓ (requires SPSS)
macOS	✓	✗
Linux	✓	✗

Analysis tools require SPSS XD API (Windows-only).

---

Development

# Compile check
python -m compileall src/spss_mcp

# Unit tests
pytest

# Live integration test (requires installed SPSS)
python test_v2_tools.py

# Format code
black src/ tests/
isort src/ tests/

# CLI commands
spss-mcp status            # Check environment
spss-mcp setup-info        # Generate config
spss-mcp configure-claude  # Auto-update Claude Code settings

---

License

MIT — see LICENSE. Copyright (c) 2026 Mehmet Raşit Narçiçek.

---

Links

• Quick Start: QUICK_START.md
• Test Report (69/69 live): TEST_REPORT.md
• Verified IBM Syntax Catalog: SYNTAX_CATALOG.md
• Tools Reference: TOOLS_REFERENCE.md
• Issues: https://github.com/rasitnarcicek/spss-mcp-extended/issues
• MCP Protocol: https://modelcontextprotocol.io