SPSS MCP Full Control

This project is a full-scope MCP front end for IBM SPSS Statistics automation.

It is designed for the architecture that actually fits SPSS:

1. IBM SPSS Statistics runs on a desktop, VM, Windows server, or batch host.
2. A local bridge beside SPSS owns the real SPSS session, executes procedures, tracks the active dataset, and captures output artifacts.
3. This MCP server exposes a broad tool surface to AI clients.
4. Any MCP-capable AI client connects to this MCP server and can drive SPSS through structured tools.

Compatible client targets include Claude Desktop, Cursor, VS Code MCP, Copilot-style MCP clients, OpenAI agent runtimes with MCP support, local agent frameworks, n8n/Make HTTP flows, and custom apps that can call the Apify Actor API.

This repository does not pretend Apify or cloud containers should directly host desktop SPSS. It assumes a proper execution bridge next to the licensed SPSS environment.

What This Actor Does

• gives AI agents a clean SPSS workflow interface
• orchestrates SPSS bridge calls from Apify
• generates MCP connection guidance
• runs structured analysis goals such as exploration, group comparison, regression, survey analysis, and forecasting
• records workflow results, summaries, and artifacts in Apify storage

What This Actor Does Not Include

• an IBM SPSS Statistics license
• hosted desktop SPSS inside Apify
• guaranteed access to private datasets unless your bridge can reach them
• final statistical judgment without user review

Scope

This is not an MVP-shaped tool list. The server surface is intentionally broad:

• session lifecycle
• dataset lifecycle
• variable inspection
• data transformation
• missing-value handling
• descriptive statistics
• crosstabs and group comparisons
• regression
• factor and cluster analysis
• forecasting
• reviewed or raw syntax execution
• export, explanation, and report generation

Why this shape

People use SPSS for a predictable set of workflows:

• clean data
• inspect variables
• run descriptive stats
• test group differences
• model relationships
• analyze surveys and segments
• build forecasts
• export and interpret results

The MCP server should map to those jobs directly instead of exposing only a generic run syntax escape hatch.

Policy model

Full control does not mean no guardrails.

• allowWrite=false by default
• allowRawSyntax=false by default
• write actions and raw syntax should be enabled only for trusted contexts
• the bridge should maintain audit logs, file path restrictions, and session history

Current state

This repository contains:

• a real MCP server for stdio and Streamable HTTP
• a broad SPSS tool surface
• a runtime policy layer
• a Python bridge skeleton that starts from SPSS-native concepts

What it does not yet contain:

• output parsers for .spv, HTML, pivot tables, or chart artifacts
• batch fallback wiring through statisticsb
• approval workflows and auth

Suggested bridge implementation

Run the bridge on the machine that has SPSS access. The bridge should implement actions such as:

• start_session
• stop_session
• list_outputs
• list_datasets
• open_dataset
• describe_dataset
• inspect_variables
• compute_variable
• recode_variable
• filter_cases
• merge_files
• handle_missing
• frequencies
• descriptives
• crosstabs
• compare_groups
• correlation
• linear_regression
• logistic_regression
• factor_analysis
• cluster_analysis
• forecast
• run_syntax
• export_output
• explain_output
• generate_report

Each action should return structured JSON:

{
  "ok": true,
  "sessionId": "abc123",
  "activeDataset": "data.sav",
  "logs": [],
  "tables": [],
  "warnings": [],
  "artifacts": [],
  "summary": {}
}

Run locally

Install dependencies:

$npm install

Start in stdio mode:

$npm run mcp:stdio

Start in HTTP mode:

$npm run mcp:http

Run As An Apify Actor

The Actor layer is built for users and AI agents that do not want to think in SPSS syntax first. They choose a goal, fill the minimum variables, and the Actor turns that into SPSS session actions.

Supported Actor goals:

• connection_guide: produce MCP/bridge connection instructions
• explore_dataset: start session, open data, describe dictionary, inspect variables
• compare_groups: run an automatic group-comparison workflow
• find_relationships: run correlation or regression depending on supplied fields
• survey_analyzer: run frequencies, crosstabs, and optional factor analysis
• forecast: run a time-series forecasting workflow
• run_syntax: run reviewed or raw SPSS syntax subject to policy
• batch: run explicit action objects for advanced users

Required production setup:

• An SPSS bridge URL reachable from Apify, usually a private server or tunnel on the machine that can run IBM SPSS Statistics.
• authToken configured as a secret input.
• The bridge must expose MCP tool calls for actions such as spss_start_session, spss_open_dataset, and spss_descriptives.

AI Client Setup

Use the same MCP server with any AI client that supports MCP over stdio or Streamable HTTP.

Local stdio example:

{
  "mcpServers": {
    "spss": {
      "command": "node",
      "args": ["/path/to/spss-mcp-full-control/src/server.js", "--transport", "stdio"],
      "env": {
        "SPSS_BRIDGE_URL": "http://127.0.0.1:8091",
        "SPSS_AUTH_TOKEN": "change-me"
      }
    }
  }
}

Remote HTTP example:

{
  "mcpServers": {
    "spss": {
      "url": "https://your-spss-mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer change-me"
      }
    }
  }
}

For AI tools without MCP, call the Apify Actor API with a goal such as explore_dataset, compare_groups, or find_relationships.

Usability rule:

The Actor should accept research-language inputs first, then produce SPSS procedure calls and artifacts. Raw syntax stays available, but it is not the main product surface.

SPSS-native bridge

See bridge/spss_bridge.py and bridge/README.md.

The bridge is shaped around:

• spss.StartSPSS()
• spss.Submit()
• active dataset state
• output viewer history
• procedure-oriented workflows

That is the right mental model for SPSS. The MCP server is only the AI-facing control plane.