# SPSS-MCP Extended

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![Platform: Windows](https://img.shields.io/badge/platform-Windows-lightgrey.svg)]()
[![MCP](https://img.shields.io/badge/protocol-MCP-green.svg)](https://modelcontextprotocol.io)
[![Version](https://img.shields.io/badge/version-2.0.0-blue.svg)]()

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 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](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)

```bash
pip install spss-mcp-extended

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

# Restart Claude Code
```

### One-Click (from source)

```bash
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)

```bash
# 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:

```bash
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`):

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

### SPSS Path (if not auto-detected)

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

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

### Slow SPSS startup?

```ini
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:

```cmd
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](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

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

```bash
# 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](LICENSE). Copyright (c) 2026 Mehmet Raşit Narçiçek.

---

## Links

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