Skip to content
Open navigation
OpenOpen workspace

For AI assistants

Crosstabs MCP server

Install the local server, let your AI request checked crosstabs from a survey file on your machine, and read insights backed by the results. Works with Claude Desktop, Claude Code, Codex, Cursor and other MCP clients; no Crosstabs account is needed.

Published by crosstabs.com · Last updated ·
How results are checkedNamed statistical review pending. Selected automated reference cases are published on the validation page.

Before you start

  • Node.js 22 or newer runs the project server. Check with node --version; install it from nodejs.org if needed.
  • uv installs the package with its own Python 3.12, whatever Python your computer has. On macOS or Linux: curl -LsSf https://astral.sh/uv/install.sh | sh. On Windows, follow uv's install guide.
  • An AI client that runs local MCP servers: Claude Desktop, Claude Code, Codex, Cursor and others.

LOCAL MCP

Install once. Your files stay on your device.

You need Node.js 22+ and uv; see before you start. uv brings its own Python 3.12.

uv tool install --python 3.12 crosstabs==1.5.3

Or, with Python 3.10 or newer and pipx: pipx install crosstabs==1.5.3.

  1. 01Install

    Run the command above. uv tool dir --bin prints the folder that holds both commands.

  2. 02Connect

    Add both commands to your AI client with their full paths; see the client setup.

  3. 03Choose the folders it may read

    Set CROSSTABS_MCP_ALLOWED_ROOTS to your survey folder, or copy the file into the exchange folder. Nothing else is readable.

  4. 04Check

    Restart the client and ask it to call get_runtime_status; it should report crosstabs 1.5.3.

FIRST PROMPT

Use Crosstabs. Check get_runtime_status, then create a project from /Users/you/Surveys/survey.csv, profile it, and run a crosstab of the main outcome by region. Explain the main finding, bases, warnings, and recommended next action.

Use your file's full path, inside a folder from step 03.

No install? Open the browser workspace, or read how to analyze survey data with ChatGPT or Claude.

Inspect a worked result first

Our customer-churn example includes downloadable aggregate counts, statistical results, interpretation, and limitations. The counts are illustrative, not a customer case study. Use it to see what a reviewable result looks like; it is not a promise of identical output or independent certification.

Check the published validation scope and keep sample bases, assumptions, and warnings in any AI-written explanation.

WHICH ONE DO I NEED?

Pick where the analysis runs.

All three use the same statistics. They differ in who drives the analysis and what data they see.

On this computer, with your AI (recommended)

The local MCP server above. Your AI builds projects, tables, weights, wave comparisons and reports from survey files on your computer. Files stay on your device; your AI client has its own data policy.

Set up the local server

In the browser

Work visually with tables, saved projects, and exports. Files are read on your device. Manual open-end coding and the outcome studio are browser-only.

Open the browser workspace

Methodology lookups only

A remote MCP endpoint for AI clients that cannot run local servers: method explanations and small count tables, no survey files. It stores nothing.

www.crosstabs.com/api/headless-mcp

See the developer reference

For exact limits and data handling, see the capacity limits and data policies.

Set up the local MCP

The local package runs on your machine, so survey files and projects stay on your device. It provides the complete statistics catalog and a saved project workflow for any MCP client that starts local (stdio) servers.

1. Install

Requirements: Node 22+ for crosstabs-headless and Python 3.10+, which uv installs for you, so the Python that came with your computer does not matter.

# Install both servers with their own Python
uv tool install --python 3.12 crosstabs==1.5.3

# Print the folder that holds crosstabs and crosstabs-headless
uv tool dir --bin

# Check the install
crosstabs --version

Prefer pipx? pipx install crosstabs==1.5.3 needs Python 3.10 or newer; which crosstabs-headless prints its path. Already manage Python environments? python3 -m pip install crosstabs==1.5.3 in a Python 3.10+ environment also works; use that environment's full path to each command.

2. Choose the folders it may read

The project server reads and writes files only in folders you allow. Without configuration that is one private exchange folder, created the first time the server starts:

  • macOS: ~/Library/Application Support/Crosstabs/headless/exchange
  • Windows: %LOCALAPPDATA%\Crosstabs\headless\exchange
  • Linux: ~/.local/share/crosstabs/headless/exchange

Copy a survey file there, or let the server read your own folders by adding CROSSTABS_MCP_ALLOWED_ROOTS to its env in the client setup below. List full paths, separated by : on macOS and Linux or ; on Windows, then restart the client. Other folders, including Downloads and Desktop, stay unreadable unless you list them.

3. Add it to your AI client

Use the full path to each command: AI apps often do not see your terminal's PATH. Replace /Users/you/.local/bin with the folder uv tool dir --bin printed, and /Users/you/Surveys with your survey folder.

Claude Desktop

{
  "mcpServers": {
    "crosstabs-headless": {
      "command": "/Users/you/.local/bin/crosstabs-headless",
      "env": {
        "CROSSTABS_MCP_ALLOWED_ROOTS": "/Users/you/Surveys"
      }
    },
    "crosstabs-statistics": {
      "command": "/Users/you/.local/bin/crosstabs"
    }
  }
}

In claude_desktop_config.json (Settings → Developer → Edit Config), then quit and reopen Claude. If crosstabs-headless says Node.js is missing, add "PATH" with the folder which node prints (for example /opt/homebrew/bin:/usr/bin:/bin) to its env.

Claude Code

claude mcp add crosstabs-headless --scope user \
  -e CROSSTABS_MCP_ALLOWED_ROOTS="$HOME/Surveys" \
  -- "$(uv tool dir --bin)/crosstabs-headless"
claude mcp add crosstabs-statistics --scope user \
  -- "$(uv tool dir --bin)/crosstabs"

Codex

codex mcp add crosstabs-headless \
  --env CROSSTABS_MCP_ALLOWED_ROOTS="$HOME/Surveys" \
  -- "$(uv tool dir --bin)/crosstabs-headless"
codex mcp add crosstabs-statistics -- "$(uv tool dir --bin)/crosstabs"

Cursor and other MCP clients

Add the same two stdio commands with their full paths, and CROSSTABS_MCP_ALLOWED_ROOTS in the env of crosstabs-headless.

Without installing (uvx)

uvx downloads and runs the package on demand. Use the full path to uvx (which uvx):

"crosstabs-headless": {
  "command": "/Users/you/.local/bin/uvx",
  "args": ["--python", "3.12", "--from", "crosstabs==1.5.3", "crosstabs-headless"],
  "env": { "CROSSTABS_MCP_ALLOWED_ROOTS": "/Users/you/Surveys" }
}

For the statistics server use "args": ["--python", "3.12", "crosstabs==1.5.3"]; in a terminal that is uvx crosstabs.

4. Check and start

Ask your AI to call get_runtime_status on both servers; each reports crosstabs 1.5.3. Then give it the first prompt above with the full path to a file in an allowed folder. If it reports that the file is outside the configured import roots, move the file or add its folder as in step 2.

Codex plugin (pins the older crosstabs 1.4.0)

codex plugin marketplace add barangaroo/crosstabs-codex-plugin --ref 857a93b32dd22f7e655ec30e3c628f70ba9a14d5
codex plugin add crosstabs@crosstabs

Codex plugin 0.4.0 adds a survey-analysis skill and starts both servers from crosstabs 1.4.0. For the tools added since, install crosstabs 1.5.3 as above instead. The plugin is installed from source; it has not been submitted to or listed in any plugin directory.

FOR DEVELOPERS

Package, provenance and capabilities

Release verification, the local tool catalog, source and license.

What was verified

The published crosstabs==1.5.3 was installed fresh from PyPI and both local servers were started: 37 project tools, and 48 statistics-server tools (39 analytical tools, six market-research tools, the database and survey-platform pull tools, plus runtime status). Both report the running package version through get_runtime_status. Its MCP Registry 1.5.3 record was checked separately. The Codex plugin's source and feature list are published separately; the plugin is not listed in any plugin directory.

Statistics procedures (since crosstabs 1.5.0): the local headless MCP tools list_statistical_procedures and run_statistical_procedure run 110 SPSS-equivalent Statistics procedures on a local project file with the same engines as the browser Statistics mode. Respondent rows stay on the device. Weights must be a saved frequency weight (ordinary inference) or sampling weight (weighted estimates only; ordinary tests withheld); untyped weights are rejected. Complex Samples procedures (CSDESCRIPTIVES, CSTABULATE, CSGLM, CSLOGISTIC, CSORDINAL, CSCOXREG) run only on a survey design approved through define_survey_design. Seeded procedures report their seed; every result cites its reference-parity tests.

The browser workspace and the local MCP run the same project engine (HeadlessCrosstabsService): the same project format, first analysis, statistics, revisions, audit history and undo. Tests compare the two before each release; that is a release check, not a certification. A saved local project can hold up to 8 MiB and all projects together up to 32 MiB, including audit and undo history; a file that imports may still be too large to save.

Local package capabilities

Runtime and analysis plans

Both servers report the running package version; reusable analysis plans with readable settings, checks for stale data, and a review of the results

Project workflow

Create, import, profile, inspect, list, export, and audit versioned research projects

Tab-book design

Row sets (multi-select questions can be based on respondents or on answers), multi-level banners, filters, tab books, significance letters, and wave comparisons. Weight columns are kept but never applied until you confirm what they mean

Manual coding

In the browser workspace, not the local MCP: open-end codebooks, review and approval, coded variables, and undo

Tracker and reporting

Replace a wave's data, find and repair changed variables between waves, create editable PPTX/DOCX reports, and refresh them without losing your manual edits

Tests

Chi-square (with Yates), G-test, Fisher's exact, McNemar's, CMH stratified test, Breslow-Day, Monte Carlo chi-square

Effect sizes

Cramér's V (bias-corrected), phi, odds ratio with CI, relative risk, risk difference, attributable risk

Measures and planning

Ordinal association, agreement, epidemiology measures, power, sample size, and multiplicity corrections

Diagnostics

Expected counts, residuals, correspondence analysis, small-cell warnings, method references, and stated limitations

Market research

TURF, penalty (JAR) analysis, key driver relative importance, NPS with margin of error, survey sample size, and data-quality flags on respondent-level rows

Local data pulls

crosstabs pull runs one read-only database query or fetches survey-platform responses on your machine and writes a file you open in Crosstabs; credentials come from environment variables

Example prompt: “Create a project from /Users/you/Surveys/wave3.sav, profile it, add age and region banners, run an unweighted tab book, and export an editable PPTX with its audit trail. If there is a weight column, keep it but do not apply it until I confirm what it means.”

Source and license

The Python 3.10+ package is declared under the MIT license and is distributed on PyPI as a wheel and downloadable source archive. The development repository is currently private; public GitHub access is not claimed here. The separately packaged plugin source repository is public. Report package or plugin issues to support@crosstabs.com. Core methods share documented conventions with the web calculators, while the package also includes additional methods with their own assumptions and output contracts. See the methods and current review status before relying on results for high-stakes work.

Package contract: crosstabs 1.5.3. Trusted Publisher: GitHub · crosstabs/crosstabs-lite · release-python-mcp.yml · environment pypi.

This evidence covers the PyPI package only, not the Codex plugin.

Verify this release

Release source SHA: a63e64a651b557099af39478ce0e57a4913fb82d.Registry verified ; provenance verified .

Prefer plain HTTP?

The free JSON API exposes chi-square, Fisher's exact, odds ratios, and 20+ measures without installing anything.

Frequently asked questions

What is the crosstabs MCP server?

The Crosstabs MCP server is a free local package. Install it with uv tool install crosstabs==1.5.3 (or pipx install crosstabs, or run it with uvx crosstabs) and add it to Claude Desktop, Claude Code, Codex, Cursor or another MCP client. Survey files and projects stay on your device; no Crosstabs account or API key is needed. A separate endpoint on www.crosstabs.com answers methodology questions and small count tables without respondent data.

How do I try Crosstabs without uploading a file?

Nothing is uploaded on any current route. Open the browser workspace and load a sample or your own file, which is parsed on your device, or install the local MCP package and point your AI client at a file on your machine. Your AI client has its own policies for the tool inputs and results it receives.

Is there an official Crosstabs plugin for Codex?

Yes, as source you install yourself: Codex plugin 0.4.0 is on public GitHub and pins the older crosstabs 1.4.0 package. For the newest tools, install crosstabs 1.5.3 directly. The plugin has not been submitted to or listed in any plugin directory.

Does the Codex plugin have full Crosstabs workspace parity?

No. The plugin's pinned package 1.4.0 covers the local project workflow: projects, imports, filters, survey designs, tab books, waves, schema repair, editable report packs, export, and audit history. Manual open-end coding stays in the browser workspace.

Why does Crosstabs say my file is outside the configured import roots?

The local server reads only folders you choose. Copy the file into the private exchange folder (on macOS ~/Library/Application Support/Crosstabs/headless/exchange), or add your folder to CROSSTABS_MCP_ALLOWED_ROOTS in the server's env in your MCP client configuration and restart the client. Separate several folders with ":" on macOS and Linux or ";" on Windows.

Why use an MCP server instead of letting the AI compute statistics itself?

Language models can make arithmetic mistakes. The MCP server executes numerical routines instead; each method still has its own assumptions, and outputs distinguish exact, asymptotic, and simulated inference.

Does the MCP server send my data anywhere?

The local servers do not upload files to Crosstabs, and they read only the folders you allow (CROSSTABS_MCP_ALLOWED_ROOTS) plus a private exchange folder. The methodology endpoint receives only the counts or topic IDs you send and stores nothing. Your AI client may also receive tool inputs and results under its own policies.