Skip to main content

Crosstabs MCP Server

Python 3.10+ License: MIT MCP

This 1.5.3 distribution provides two local MCP servers: 39 statistical tools, 6 market-research tools, 1 local database pull tool, 1 survey-platform pull tool and one runtime-status tool (48 registered tools), and 37 headless research workflow tools including runtime status, portable analysis plans, guided weighting and Statistics procedures. Both servers report their executing package version through get_runtime_status. Individual statistical tools report whether their inference is exact, asymptotic, or simulated. Publication evidence for earlier package versions does not establish this distribution's publication or certification status. Check the executing runtime rather than inferring its version from an installed plugin manifest.

1.5.3, 1.5.2 and 1.5.1 are patch releases with no tool added or removed (see "Changes in 1.5.3", "Changes in 1.5.2" and "Changes in 1.5.1" below). New in 1.5.0 (see "Changes in 1.5.0" below): six market-research tools and a local read-only database pull (crosstabs pull and pull_database_query) and a survey-platform pull for 14 platforms (crosstabs pull <platform> and pull_survey_responses) on the statistical server, and two headless Statistics procedure tools, list_statistical_procedures and run_statistical_procedure, covering 110 SPSS-equivalent procedures.

Guided weighting: supply complete trusted population margins to preview_raking_weights, review its aggregate balance/trim/ESS diagnostics, then explicitly call apply_raking_weights with the reviewed fingerprint, warning acknowledgements, human approval, expected revision and idempotency key. No respondent weight vector is returned. Apply creates a new saved sampling-weight column, preserving audit/replay/undo; it grants no survey-design or ordinary-inference approval.

Both commands are local stdio servers. The package contains no HTTP/SSE transport or cloud-deployment configuration; network transport arguments are refused. The only outbound connection the package makes is the one you ask for with crosstabs pull / pull_database_query / pull_survey_responses: from your machine to your own database or survey-platform account. Use the separate five-tool public MCP at crosstabs.com only for bounded aggregate matrices and public evidence.

crosstabs is an aggregate calculator. Its ordinary inferential tools require caller-attested inputSemantics="integer_frequency_counts" and non-negative integer frequency cells; they do not accept respondent, calibration, raking, or complex-survey weights. Use crosstabs-headless for a completed supported saved survey design and its disclosed design-aware inference.

Inferential aggregate calls also require weighted=false. The two descriptive aggregate visual tools, stacked_bar_data and correspondence_analysis, require inputSemantics="descriptive_aggregate_values"; their fractional values are not survey-weighted inference. mosaic_plot_data remains an inferential residual diagnostic and therefore requires integer frequency counts. Missing or unsupported semantics, fractional cells, non-finite values, negative values, and unsafe integers are rejected before any statistics are returned. proportion_ci separately requires countSemantics="integer_binomial_counts" and safe integer binomial counts for successes and total.

Features

Core Statistical Tests

Test Description
Chi-square Pearson's chi-square test of independence
G-test Likelihood-ratio alternative with an asymptotic p-value
Fisher's exact Two-sided fixed-margin exact p-value for 2×2 integer counts
McNemar's Exact two-sided binomial inference for fewer than 20 discordant pairs; continuity-corrected chi-square otherwise

Effect Sizes & Measures

Measure Use Case
Cramér's V Effect size for any table size (with bias correction)
Phi coefficient Effect size for 2×2 tables
Odds ratio Association strength with a large-sample Woolf log interval
Relative risk Risk comparison between groups
Risk difference Absolute risk reduction
Attributable risk Population-level impact

Ordinal Measures

Measure Description
Spearman's rho Rank correlation
Kendall's tau Concordance measure
Goodman-Kruskal gamma Ordinal association
Somers' D Asymmetric ordinal measure
Stuart's tau-c Rectangular table measure

Agreement & Reliability

Measure Description
Cohen's kappa Inter-rater agreement with an asymptotic normal interval
Weighted kappa Linear/quadratic agreement with an asymptotic normal interval

Advanced Analysis

Tool Description
CMH test Stratified analysis with a Robins-Breslow-Greenland pooled-OR interval
Breslow-Day Test homogeneity of odds ratios
Correspondence analysis Dimensionality reduction for tables
Monte Carlo chi-square Fixed-margin simulated p-value estimate
Power analysis Equal-group, two-sided normal approximation using Cohen's h
Multiple comparisons Bonferroni and FDR corrections

Installation

Before you start

  • Node.js 22+ for crosstabs-headless (the project server). Check with node --version.
  • Python 3.10+. The simplest route is uv, which installs its own Python, so the Python that came with your computer (for example 3.9 on macOS) does not matter. Install uv on macOS or Linux with curl -LsSf https://astral.sh/uv/install.sh | sh; on Windows, follow uv's installation guide.
uv tool install --python 3.12 crosstabs
uv tool dir --bin          # the folder holding crosstabs and crosstabs-headless
crosstabs --version
crosstabs-headless --help

Alternatives:

pipx install crosstabs                 # needs Python 3.10+; `which crosstabs-headless` prints its path
python3 -m pip install crosstabs       # inside a Python 3.10+ virtual environment
uvx crosstabs                          # run the statistics server without installing
uvx --from crosstabs crosstabs-headless

Inspect the public source distribution

python -m pip download --no-deps --no-binary=:all: crosstabs

The development repository is currently private. PyPI publishes the package's source archive; email support@crosstabs.com for issue reports or source-access questions.

Quick Start

The two servers

# Focused statistical calculators (Python 3.10+)
crosstabs

# End-to-end research workspace (Python 3.10+ and Node.js 22+)
crosstabs-headless

Both are stdio MCP servers: your AI client starts them. Run them by hand only to check the install (--version, --help). Or directly:

python -m crosstabs_mcp.server

Choose the folders it may read

crosstabs-headless reads survey files and writes reports only in folders you allow. With no configuration that is one private exchange folder, created the first time the server starts:

System Exchange folder
macOS ~/Library/Application Support/Crosstabs/headless/exchange
Windows %LOCALAPPDATA%\Crosstabs\headless\exchange
Linux ~/.local/share/crosstabs/headless/exchange (or under $XDG_DATA_HOME)

Copy a file there, or list your own folders in CROSSTABS_MCP_ALLOWED_ROOTS in the server's env in your MCP client configuration, then restart the client. Use full paths (a leading ~ is expanded) separated by : on macOS and Linux or ; on Windows. Folders you list are added to the exchange folder; nothing else on the computer is readable. get_runtime_status reports the folders as storage.importRoots, and a file outside them is refused with a message that names the exchange folder and the variable. crosstabs-headless --help prints the exchange folder for your computer.

Configure an MCP client

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

Claude Desktop (claude_desktop_config.json: Settings → Developer → Edit Config; on macOS ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "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"
    }
  }
}

If crosstabs-headless reports that 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"

Without installing (uvx): use the full path to uvx (which uvx) as the command, with "args": ["--python", "3.12", "--from", "crosstabs", "crosstabs-headless"].

Then ask your AI: "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."

The headless server stores project state and generated artifacts under the local application-data directory (CROSSTABS_DATA_DIR overrides it). Deterministic calculations stay on the machine. It makes no hosted-AI, account, or remote-project call. Manual open-end coding remains a browser-workspace feature rather than a local MCP operation.

Headless workflow tools

create_project, import_dataset, profile_dataset, define_row_set, define_banner, apply_filter, set_weight, define_survey_design, run_table, run_tab_book, compare_waves, undo_change, replace_dataset, detect_schema_drift, repair_schema, generate_report_pack, refresh_report_pack, export_project, list_projects, inspect_project, get_audit_history, import_project, render_project_table, update_variable_metadata, propose_transformation, review_transformation, apply_transformation, undo_transformation, and run_complex_survey_method.

Project-package import reads a checksummed full-data copy from an allowed folder. It never overwrites a project. Rendering uses a saved table/revision/evidence ID, not an ordinary re-analysis of caller-supplied cells. Inference-changing edits retain approval, revision and replay guards. The local JSON store enforces 8 MiB per serialized project (including undo/audit) and 32 MiB per database (including replay records); parser maxima are not persistence guarantees.

Mutations use expected revisions and idempotency keys. Results include structured warnings, evidence IDs, audit records, and MCP resources for generated files. For a detected multi-select row dimension, define_row_set may additionally set multipleResponseDenominator to cases or responses; ordinary and compound row sets reject that option rather than silently applying it.

Monte Carlo workload envelope

Fixed-margin Monte Carlo accepts at most 100 rows, 100 columns, and 1,000 cells, with a total frequency of 9,007,199,254,740,991. It admits 100,000 simulations and 20,000,000 cell-simulations. It samples chunks of at most 512 simulations under a 32 MiB estimated numeric peak and a 30-second server deadline. The returned workload object records the admitted dimensions, cell-simulation product, chunk size, memory estimate, memory ceiling, and deadline. The memory estimate covers the numeric simulation path, not the MCP transport's parsed JSON body. A supplied seed is reproducible for the same table, simulation count, and package versions. MCP cancellation is observed between chunks; an individual SciPy draw cannot be interrupted mid-chunk.

Usage Examples

Once configured, Claude can perform statistical analysis:

Chi-square Test

User: Test if there's an association between treatment and outcome:
      Treatment A: 50 success, 30 failure
      Treatment B: 20 success, 40 failure

Claude: [Uses chi_square_test with matrix [[50,30],[20,40]]]
        χ² = 11.67, p = 0.0006
        Cramér's V = 0.29 (small-medium effect)
        There is a significant association between treatment and outcome.

Odds Ratio

User: Compare an adverse outcome between exposure groups:
      Exposed: 30 outcome-present, 70 outcome-absent
      Unexposed: 15 outcome-present, 85 outcome-absent

Claude: [Uses odds_ratio with matrix [[30,70],[15,85]]]
        OR = 2.43 (95% CI: 1.21-4.87)
        Exposure is associated with 143% higher odds of the outcome.

The epidemiology tools (odds_ratio, relative_risk, risk_difference, and attributable_risk) use one explicit orientation: [[exposed outcome+, exposed outcome-], [unexposed outcome+, unexposed outcome-]]. They return machine-readable zero/infinite/undefined states rather than silently continuity-correcting point estimates. Attributable/prevented fractions require causal identification assumptions; an association alone does not establish the counterfactual effect of removing an exposure.

Fisher's Exact Test

User: I have a small sample: [[3,1],[1,5]]. Is it significant?

Claude: [Uses fishers_exact with the matrix]
        p = 0.190476 (two-tailed exact)
        Not statistically significant at α=0.05.

Available Tools

Tool Name Description
chi_square_test Chi-square test of independence
g_test G-test (likelihood ratio)
fishers_exact Fisher's exact test (2×2)
mcnemar_test McNemar's test for paired data
odds_ratio Odds ratio with CI
relative_risk Relative risk with CI
risk_difference Risk difference with CI
cramers_v Cramér's V effect size
phi_coefficient Phi for 2×2 tables
cohens_kappa Cohen's kappa
weighted_kappa Weighted kappa
spearmans_rho Spearman's rank correlation
kendalls_tau Kendall's tau-b
goodman_kruskal_gamma Gamma coefficient
somers_d Somers' D
tau_c Stuart's tau-c
cmh_test Cochran-Mantel-Haenszel
breslow_day_test Breslow-Day test
linear_trend_test Linear-by-linear association
correspondence_analysis Correspondence analysis
monte_carlo_chi_square Fixed-margin Monte Carlo p-value estimate
power_analysis Two-sided normal-approximation power/sample size using Cohen's h
bonferroni_correction Bonferroni p-value adjustment
fdr_correction Benjamini-Hochberg FDR
standardized_residuals Cell residuals
post_hoc_chi_square Post-hoc chi-square decomposition
proportion_ci Confidence interval for proportion
check_assumptions Validate chi-square assumptions
recommend_test Method suggestions with assumption caveats
mosaic_plot_data Data for mosaic visualization
stacked_bar_data Data for stacked bar chart
attributable_risk Attributable risk measures
chi_square_yates Yates' continuity correction
effect_size Multiple contingency-table effect sizes
lambda_coefficient Goodman–Kruskal lambda
uncertainty_coefficient Theil's uncertainty coefficient
detect_outliers Outlier detection
crosstab_from_data Build table from raw data
crosstab_from_csv Build table from CSV

Market-research tools (added in 1.5.0)

These six tools were added in 1.5.0 and are not part of the earlier 1.4.0 distribution. They are registered on the crosstabs statistical server alongside the 39 statistical tools and runtime status. The tools take respondent-level rows (one object per respondent) and follow the definitions and defaults of the browser-local calculators at https://www.crosstabs.com/tools, so both report the same numbers. They are outside the pending named statistical review scope.

Market-research tool Description
turf_analysis TURF reach and frequency: exhaustive up to 50,000 combinations, otherwise greedy, plus an incremental reach ladder
penalty_analysis Just-about-right penalty analysis: mean drops, weighted penalties, Welch tests, 20% action line
key_driver_analysis Shapley R² decomposition and Johnson's relative weights with VIF and collinearity warnings
nps_analysis Net Promoter Score with multinomial standard errors, segment and two-group tests
survey_sample_size Completes for a margin of error, margin of error for n, two-proportion group sizes
data_quality_flags Speeder, straight-liner, duplicate and incomplete-interview flags; nothing is removed

Statistics procedure tools (added in 1.5.0)

These two headless tools were added in 1.5.0 and are not part of the earlier 1.4.0 distribution. They run in crosstabs-headless and bring its catalog from 35 to 37 headless research workflow tools.

Headless tool Description
list_statistical_procedures Catalog of 110 SPSS-equivalent Statistics procedures (id, SPSS command, required inputs, weight support, missing-value handling, randomness, validation references); pass procedureId for its options JSON Schema
run_statistical_procedure Run one procedure on a local project wave with validated options and an optional saved frequency or sampling weight; returns the engine's structured tables, footnotes, validation references and a deterministic input fingerprint

The procedures are the same pure TypeScript engines as the browser Statistics mode, so both report the same numbers. Weights are never guessed: weightId must name a saved project weight declared as frequency (exact counts; ordinary inference) or sampling (weighted point estimates; ordinary significance tests withheld). Unspecified, calibration and analytic weights are rejected, and procedures that are unweighted reject a weight instead of ignoring it. Complex Samples procedures run only on a saved survey design approved through define_survey_design; inline designs are rejected. Seeded procedures echo their seed. Three browser procedures that write sample selections or browser-only plan state (cs-plan, cs-select, sample) are not exposed.

Pull from a database (added in 1.5.0)

Browsers cannot talk to databases, and crosstabs.com will not run a hosted proxy that holds your credentials or respondent rows. crosstabs pull runs on your own machine: it connects to your database with your credentials, runs one read-only query and writes a file that the crosstabs.com workspace opens locally (.sav, .dta, .csv or .xlsx; .parquet is also written for other tools, but the workspace does not open it yet). The query, credentials and rows never go to crosstabs.com.

Install the db extra plus your database's driver. The core crosstabs install does not include them, and a missing one produces an error naming the extra to install:

Extra Database Driver installed
crosstabs[db] SQLite (stdlib) SQLAlchemy, pyreadstat, pyarrow, sqlglot, PyYAML, openpyxl
crosstabs[postgres] PostgreSQL psycopg 3
crosstabs[redshift] Amazon Redshift (PostgreSQL protocol) psycopg 3
crosstabs[mysql] MySQL / MariaDB PyMySQL
crosstabs[mssql] SQL Server / Azure SQL pyodbc (needs Microsoft ODBC Driver 18 installed separately)
crosstabs[oracle] Oracle python-oracledb (thin mode, no Instant Client needed)
crosstabs[snowflake] Snowflake snowflake-sqlalchemy
crosstabs[databricks] Databricks SQL / Unity Catalog databricks-sqlalchemy, databricks-sql-connector, databricks-sdk
crosstabs[bigquery] Google BigQuery sqlalchemy-bigquery
crosstabs[duckdb] DuckDB duckdb-engine
crosstabs[all-db] all of the above

Put the SQLAlchemy URL in an environment variable and pass its name with --url-env (a --url value is visible in shell history and the process list). Passwords and tokens are masked in every message, log line and error.

pip install "crosstabs[postgres]"
export CROSSTABS_DB_URL='postgresql://analyst:PASSWORD@db.example.com:5432/surveys'
crosstabs pull --url-env CROSSTABS_DB_URL --table public.responses --out wave3.sav
crosstabs pull --url-env CROSSTABS_DB_URL --query-file wave3.sql \
  --labels labels.yaml --column-comments --out wave3.sav

Snowflake (password, key pair or browser SSO):

pip install "crosstabs[snowflake]"
# Key-pair authentication: the URL holds no secret.
export SNOWFLAKE_URL='snowflake://ANALYST@myorg-myaccount/SURVEYS/PUBLIC?warehouse=ANALYTICS_WH&role=SURVEY_READER'
export SNOWFLAKE_PRIVATE_KEY_PATH="$HOME/.ssh/snowflake_rsa_key.p8"
export SNOWFLAKE_PRIVATE_KEY_PASSPHRASE='...'   # only for an encrypted key
crosstabs pull --url-env SNOWFLAKE_URL --table SURVEYS.PUBLIC.RESPONSES --column-comments --out wave3.sav
# Single sign-on in the system browser:
export SNOWFLAKE_URL='snowflake://me%40example.com@myorg-myaccount/SURVEYS/PUBLIC?warehouse=ANALYTICS_WH&authenticator=externalbrowser'

Databricks (personal access token or OAuth machine-to-machine):

pip install "crosstabs[databricks]"
export DATABRICKS_URL='databricks://token@adb-1234567890.12.azuredatabricks.net?http_path=/sql/1.0/warehouses/abcdef&catalog=main&schema=surveys'
export DATABRICKS_TOKEN='dapi...'                 # personal access token, or:
export DATABRICKS_CLIENT_ID='...' DATABRICKS_CLIENT_SECRET='...'   # service principal (OAuth M2M)
crosstabs pull --url-env DATABRICKS_URL --table main.surveys.responses --column-comments --out wave3.sav

A token may also be written in the URL (databricks://token:dapi...@host?...). Unity Catalog three-part names (catalog.schema.table) work with --table and in queries.

BigQuery and SQL Server:

pip install "crosstabs[bigquery]"
gcloud auth application-default login         # or GOOGLE_APPLICATION_CREDENTIALS=key.json
export BQ_URL='bigquery://my-project/surveys'
crosstabs pull --url-env BQ_URL --query "SELECT * FROM surveys.responses WHERE wave = 3" --out wave3.sav

pip install "crosstabs[mssql]"                # plus Microsoft ODBC Driver 18 for SQL Server
export MSSQL_URL='mssql+pyodbc://analyst:PASSWORD@sql.example.com:1433/Surveys?driver=ODBC+Driver+18+for+SQL+Server&Encrypt=yes'
crosstabs pull --url-env MSSQL_URL --table dbo.Responses --out wave3.sav

Other URL forms: mysql://user:pw@host/db, oracle://user:pw@host:1521/?service_name=ORCL, redshift://user:pw@cluster.region.redshift.amazonaws.com:5439/dev, duckdb:///path/survey.duckdb, sqlite:///path/survey.db.

Read-only by design. Only a single SELECT or WITH statement is accepted (parsed with sqlglot; a conservative keyword check is used if sqlglot is missing). INSERT, UPDATE, DELETE, DROP, DDL, SELECT ... INTO, FOR UPDATE, data-modifying CTEs and known side-effect functions are refused. The session is also opened read-only where the database supports it (SQLite, DuckDB, PostgreSQL, MySQL, Oracle), a statement timeout is set (--timeout, default 300 seconds) and the transaction is rolled back. Snowflake, Databricks, BigQuery and SQL Server have no read-only session switch, so use a login or role with SELECT-only grants; that grant is the real security boundary.

Limits. Results are refused above 1,000,000 rows, 1,000 columns or 20,000,000 cells, the same limits the browser import applies. --limit N keeps the first N rows instead and the summary reports truncated: true.

Types. Integers, floats, text, booleans (1/0 in .sav/.dta), dates, timestamps (time-zone-aware values converted to UTC) and times are preserved; decimals become floating point with a note; NULL becomes system-missing (and an empty string for text in .sav/.dta, which have no missing text value). JSON, binary and UUID values are stored as text with a note. Nothing is recoded and no weight is guessed: text is coded 1..k with value labels only for columns named in --categorical or marked categorical in the labels file. Column names that SPSS/Stata cannot use are renamed, with the original kept as the variable label and reported in the summary. Variable labels can come from database column comments with --column-comments and --table (PostgreSQL, MySQL, Oracle, SQL Server, Snowflake COMMENT, Databricks and DuckDB comments; BigQuery column descriptions).

Labels file (--labels labels.yaml, or .json):

variables:
  resp_id: Respondent ID              # a string is a variable label
  q1:
    label: Overall satisfaction
    measure: ordinal                  # nominal | ordinal | scale
    values: {1: Very poor, 5: Excellent}
    missing: [99]                     # user-missing codes (.sav only, up to 3)
  tier:                               # a text column coded on request
    categorical: true
    order: [low, medium, high]        # codes 1, 2, 3; unlisted values are an error

The same engine is available to agents on the statistical MCP server. The tool takes the name of the environment variable that holds the URL, never the URL or a password:

Database tool Description
pull_database_query Run one read-only SELECT/WITH query (or read a table) through a connection URL held in a named environment variable, and write a local .sav/.dta/.csv/.xlsx/.parquet file; returns the path, row and column counts, per-column schema and the read-only protections applied

Set the variable in the MCP client's server configuration ("env": {"CROSSTABS_DB_URL": "..."}) and call the tool with connectionEnvVar="CROSSTABS_DB_URL" and an absolute outputPath. Existing files are not overwritten unless overwrite=true.

Pull from a survey platform (added in 1.5.0)

crosstabs pull <platform> downloads responses from your survey-platform account on your own machine and writes a labelled file the crosstabs.com workspace opens (.sav keeps every label; .dta, .csv, .xlsx and .parquet are also written). Credentials are read from environment variables only: there is no flag or tool argument that takes a token, key, secret or password, and every message masks them. Responses never go to crosstabs.com.

pip install "crosstabs[surveys]"   # pyreadstat, pyarrow, openpyxl, google-auth-oauthlib
crosstabs pull qualtrics --help    # credentials, settings and an example per platform

Every platform is mapped onto one model:

  • question wording becomes the variable label and choices become value labels (platform recode values are kept when they are numeric and unique, otherwise choices are numbered 1..n in display order);
  • a single choice or NPS question is one numeric variable; a multi-select is one 0/1 variable per choice (Q2_1, Q2_2, ...; "Not selected"/"Selected") grouped as a dichotomous multiple-response set; a grid is one variable per row; a multi-answer grid is one set per row; a ranking is one rank variable per item; "other, please specify" text is a _other text variable;
  • only complete responses are kept unless you pass --include-partial, and response_complete (1 complete, 0 partial) is always written;
  • weights are never guessed or applied: a platform weight field (embedded data, hidden field, calculated field) is carried as a plain numeric variable;
  • IP address, location and contact fields are left out unless you pass --include-identifiers.

Next to the data file, <name>.survey.json records the platform, survey, export time, filters, response counts, question definitions and the multiple-response sets (in the same shape pyreadstat.read_sav(...).mr_sets returns; pyreadstat cannot write SPSS MR-set records). The workspace finds the sets again on import because their variables follow the <question>_<n> 0/1 pattern its multi-select detector recognises. Results above 1,000,000 responses, 1,000 variables or 20,000,000 cells are refused, as for the database pull.

Platform Credentials (environment) Example
Qualtrics QUALTRICS_API_TOKEN, or QUALTRICS_CLIENT_ID + QUALTRICS_CLIENT_SECRET (OAuth client credentials) crosstabs pull qualtrics --survey SV_abc123XYZ --datacenter iad1 --out wave3.sav
SurveyMonkey SURVEYMONKEY_ACCESS_TOKEN crosstabs pull surveymonkey --survey 405060708 --region eu --out pulse.sav
Medallia Experience Cloud MEDALLIA_CLIENT_ID + MEDALLIA_CLIENT_SECRET (or MEDALLIA_ACCESS_TOKEN); MEDALLIA_TOKEN_URL, MEDALLIA_QUERY_URL crosstabs pull medallia --survey relationship-2026 --fields e_responsedate,e_ltr,q_osat --since 2026-01-01 --out cx.sav
Alchemer ALCHEMER_API_TOKEN + ALCHEMER_API_TOKEN_SECRET crosstabs pull alchemer --survey 7654321 --region us --out event.sav
Typeform TYPEFORM_TOKEN crosstabs pull typeform --survey aBcD1234 --include-partial --out feedback.sav
Google Forms GOOGLE_OAUTH_CLIENT_SECRETS (desktop client JSON path; browser sign-in on 127.0.0.1), optional GOOGLE_OAUTH_TOKEN_CACHE, or GOOGLE_OAUTH_ACCESS_TOKEN crosstabs pull google-forms --survey 1FAIpQLSf... --out volunteers.sav
Forsta Surveys (Decipher) DECIPHER_API_KEY; DECIPHER_SERVER crosstabs pull decipher --survey selfserve/53b/proj1234 --server selfserve.decipherinc.com --out tracker.sav
QuestionPro QUESTIONPRO_API_KEY crosstabs pull questionpro --survey 11223344 --region us --out staff.sav
Jotform JOTFORM_API_KEY crosstabs pull jotform --survey 241234567890123 --out intake.sav
SurveySparrow SURVEYSPARROW_TOKEN crosstabs pull surveysparrow --survey 555 --out nps.sav
REDCap REDCAP_API_TOKEN; REDCAP_API_URL crosstabs pull redcap --survey cohort --api-url https://redcap.example.edu/api/ --forms baseline --out cohort.sav
KoboToolbox KOBO_API_TOKEN; KOBO_SERVER crosstabs pull kobo --survey aXyZ123abc --server eu.kobotoolbox.org --out household.sav
ODK Central ODK_CENTRAL_TOKEN, or ODK_CENTRAL_EMAIL + ODK_CENTRAL_PASSWORD, or ODK_CENTRAL_APP_USER_TOKEN; ODK_CENTRAL_URL crosstabs pull odk-central --survey 3/water_audit --server https://central.example.org --out audit.sav
LimeSurvey LIMESURVEY_USERNAME + LIMESURVEY_PASSWORD; LIMESURVEY_API_URL crosstabs pull limesurvey --survey 123456 --api-url https://survey.example.org/index.php/admin/remotecontrol --out commute.sav

Platform notes:

  • Qualtrics uses the survey-definitions API and an asynchronous JSON export (start, poll, download zip). --include-partial adds a second export of in-progress responses. Export tags name the variables; loop & merge iterations become 1_Q9, 2_Q9 (v1_Q9 in .sav); embedded data is kept. Side-by-side, heat-map, drill-down and other rich types are listed in the notes and not exported.
  • SurveyMonkey follows /responses/bulk links.next pages and backs off on HTTP 429 using Retry-After or the X-Ratelimit-App-Global-Minute-Reset header. Disqualified and over-quota responses are never kept.
  • Medallia depends on your contract: the Query API endpoint, the OAuth token URL, the fields your data-access role may read and the rate limits are set per instance. Pass the field ids with --fields; value labels come from the labels returned with each value. The feedback object only holds completed records, so --include-partial has no effect.
  • REDCap parses "1, Yes | 2, No" choices; checkboxes keep REDCap's field___code names (minus signs become _); a record is complete when every <instrument>_complete field present is 2.
  • Decipher reads the JSON datamap for labels and the data API with cond=qualified (with --include-partial status 4 is kept as partial; terminated and over-quota records are never kept). --layout passes a layout id.
  • Google Forms, Jotform, KoboToolbox and ODK Central only return submitted responses. ODK labels and choices come from the XForm (itext and secondary instances); repeat groups are not flattened (Kobo and ODK).
  • QuestionPro, SurveySparrow and LimeSurvey connectors are thinner: they cover the documented list/response endpoints and the common question types.

The same engine is available to agents on the statistical MCP server. The tool takes the platform, survey id, an absolute output path and non-secret settings; credentials come from the MCP server's environment ("env": {"QUALTRICS_API_TOKEN": "..."} in the client configuration):

Survey tool Description
pull_survey_responses Pull responses from one of 14 survey platforms with credentials from environment variables and write a local labelled .sav/.dta/.csv/.xlsx/.parquet file plus a .survey.json sidecar; returns the paths, complete/partial counts, multiple-response sets, per-variable schema and notes

Existing files are not overwritten unless overwrite=true. Google Forms sign-in opens a browser on the machine running the server unless GOOGLE_OAUTH_ACCESS_TOKEN is set.

Connect crosstabs.com to a database or survey platform (local bridge)

crosstabs connect runs a small bridge on your own computer so the crosstabs.com workspace can open a database table, a query result, survey responses or a CSV file without any Crosstabs server in between.

pip install "crosstabs[db]"            # plus e.g. crosstabs[postgres] for other databases
crosstabs connect --sqlite survey.db   # or --duckdb, --url-env CROSSTABS_DB_URL, --csv-dir ~/exports

The bridge prints a port and a one-time pairing code. In the workspace choose Use the local bridge, enter the port and select Connect: a window served by the bridge opens, you type the pairing code there, pick a table or write one SELECT query, preview it and send it. The rows go from that window to the crosstabs.com window by postMessage; the workspace then runs its normal import review.

  • Listens on 127.0.0.1 only (default port 47613, or a free port if taken); requests with any other Host header are refused.
  • crosstabs.com never fetches the bridge, so there are no CORS headers, no mixed-content subresources and no Local Network Access subresource requests.
  • Data is posted only to https://www.crosstabs.com or https://crosstabs.com (--allow-vercel-previews adds crosstabs-lite preview deployments, --dev adds http(s)://localhost:<port>).
  • Credentials come from environment variables (CROSSTABS_*, or names given with --url-env / --allow-env) or are typed into the bridge window and kept in memory; they are never put in a URL or sent to crosstabs.com.
  • Queries go through the crosstabs pull engine: single SELECT/WITH only, read-only session where supported, statement timeout, credential redaction, and the browser import limits (50 MB per transfer).
  • Survey platforms (the 14 crosstabs pull <platform> sources) are added in the bridge window with Add a connection; tokens come from the platform's environment variables or are typed there and kept in memory. Responses travel as a labelled .sav, and multiple-response set definitions from the .survey.json sidecar travel with them so the workspace keeps the sets and their choice wording.
  • Stops after 30 minutes without requests (--idle-timeout).

Further source kinds register through crosstabs_mcp.bridge_sources.register_source_kind. The threat model is in the repository's docs/local-connection-bridge.md.

Changes in 1.5.3

A patch release. No tool is added or removed and every input schema is unchanged: the statistical server still registers 48 tools and the headless server 37. All changes are in the bundled crosstabs-headless server, which is rebuilt from the current crosstabs.com import and project code.

  • import_project: project packages exported by the current crosstabs.com workspace verify again. Their manifest now says definition-only packages can be applied to new data; 1.5.2 rejected that wording, so it refused every newly exported package. Packages with the earlier wording still verify. A definition-only package still cannot be imported as a working project.
  • import_dataset recognises survey-platform exports on Excel as well as CSV, and more of them: besides the Qualtrics (now also two-row and legacy V1-V10) and SurveyMonkey layouts, Forsta Surveys (Decipher), Forsta Plus (Confirmit), Alchemer, Typeform, Google Forms, QuestionPro, 问卷星, 腾讯问卷, 金数据, Zoho Survey, SurveyCTO, ODK Central and KoboToolbox. Platform header rows are removed, question text becomes the variable label, and system columns are marked as identifiers or metadata. Customer-feedback files (an NPS or satisfaction item plus a response date) are recognised by content, and Medallia by its field IDs. Each detection is reported in the parse notes.
  • import_dataset reads Big5 (Traditional Chinese) and EUC-KR/CP949 (Korean) CSV exports, which were decoded as the wrong encoding before.
  • import_dataset converts columns of grouped numbers (1,234,567.50), Indian lakh/crore grouping (12,34,56,789) and ₹, ₩, Rs/INR amounts, only when every value in the column is such a number. IDs with leading zeros, phone numbers, postal codes and lists like 1,2,3 stay text. Each conversion is noted per column.
  • import_dataset no longer rejects a file because of hostile column names (toString, __proto__, constructor) or a single value over 32,768 characters: such columns are renamed and such values shortened, with a note.
  • import_dataset retries compressed .sav files with harmless exporter framing quirks (empty extension records, mismatched display records, stray bytes after the data) once with that framing removed; values, labels and missing definitions are unchanged.
  • Both servers report package version 1.5.3 through get_runtime_status.

Changes in 1.5.2

A patch release. No tool is added or removed and every input schema is unchanged: the statistical server still registers 48 tools and the headless server 37.

  • crosstabs-headless: a file outside the allowed folders is refused with a message that lists the folders it can read, names the private exchange folder, and gives a CROSSTABS_MCP_ALLOWED_ROOTS example for the client's env; the same facts are in the error details. An output path outside them gets the matching message, and a configured folder that does not exist is named in its own error.
  • crosstabs-headless: get_runtime_status reports storage.importRoots, storage.exchangeDirectory, storage.importRootsSource and the variable name, and the server instructions tell the AI where files can be read. The project store location stays private.
  • crosstabs-headless: folders listed in CROSSTABS_MCP_ALLOWED_ROOTS are added to the exchange folder instead of replacing it, and a leading ~ expands to the home folder. Nothing outside those folders is readable.
  • crosstabs-headless --help (-h, help) prints usage, the Node.js 22 requirement, this computer's exchange folder and how to allow other folders; --version (-V) prints the version. Neither starts Node. Before, both were passed to the server and printed nothing.
  • Statistics server (crosstabs): the MCP handshake reports the name crosstabs and the package version (it said crosstabs-enhanced with the mcp library's version) and now sends short instructions.
  • Statistics server: tool descriptions are a summary sentence, any caveats, a Parameters: list covering every input (including inputSemantics, weighted and countSemantics) and one Returns: line, instead of indented docstrings.
  • The evidence-graph resource version is 2026-10-28.
  • This README leads with uv tool install, lists prerequisites first, and shows Claude Desktop, Claude Code, Codex and uvx configurations with full paths and CROSSTABS_MCP_ALLOWED_ROOTS.
  • Both servers report package version 1.5.2 through get_runtime_status.

Changes in 1.5.1

A patch release. No tool is added or removed: the statistical server still registers 48 tools and the headless server 37, with the same names and input schemas.

  • crosstabs pull, pull_database_query and pull_survey_responses: database errors are plain sentences for common cases (no such table or column, syntax error, permission denied, sign-in and connection failures). The SQL text that SQLAlchemy appends and its documentation link are dropped. The driver's own wording, with credentials masked, follows on a Detail: line in the terminal and in MCP tool errors.
  • crosstabs connect: the bridge window and its pages follow the language of the crosstabs.com window that opened them (or the browser's language), in the workspace's ten languages. Errors carry a code so they can be translated, and database errors show a plain sentence with the driver's wording under Technical detail.
  • crosstabs connect: the preview respects the row limit and states its size (for example "250 rows × 6 columns"). Tables with fewer than 10 rows show the workspace's small-table warning before Send. A typed query clears and disables the table list, and the window says which one Send uses. "Keep identifying fields" is a checkbox that keeps them only when ticked. Setting help for KoboToolbox/ODK Central servers and REDCap/SurveySparrow API URLs names the right platform. The start-up banner says when port 47613 was busy and another port was used.
  • crosstabs --help (also -h, help) lists the connect and pull commands, and crosstabs --version (-V) prints the version. With no arguments crosstabs still runs the stdio MCP server; other arguments still fail closed and now point to --help.
  • Headless server (crosstabs-headless): rebuilt from current source. NOMREG through run_statistical_procedure counts model parameters from the design, so a predictor that separates the outcome no longer collapses the likelihood-ratio degrees of freedom, and it reports complete or quasi-complete separation in its warnings. list_statistical_procedures now names PRINCALS and OVERALS among the procedures that are not exposed (they run in the browser workspace only); the procedure count stays 110.
  • The survey-platform pull's HTTP User-Agent reports the executing package version.
  • PyPI project links point to public crosstabs.com pages: Homepage https://www.crosstabs.com/, Documentation https://www.crosstabs.com/developers and Support https://www.crosstabs.com/support. The "Source" link, which pointed back at PyPI, is removed.
  • Both servers report package version 1.5.1 through get_runtime_status.

Changes in 1.5.0

  • Statistical server (crosstabs): adds six market-research tools (turf_analysis, penalty_analysis, key_driver_analysis, nps_analysis, survey_sample_size, data_quality_flags) and the local read-only database pull pull_database_query (also crosstabs pull) and the survey-platform pull pull_survey_responses (also crosstabs pull <platform>), for 48 registered tools. The 39 statistical tools, their input-semantics contracts and the phase-1 review scope are unchanged; the market-research, database and survey tools sit outside that scope. Database drivers are optional extras (crosstabs[db], crosstabs[postgres], crosstabs[snowflake], crosstabs[databricks], ...); the survey pull's file writers and Google sign-in are in crosstabs[surveys].
  • Headless server (crosstabs-headless): adds list_statistical_procedures and run_statistical_procedure (110 SPSS-equivalent Statistics procedures using the browser Statistics-mode engines), for 37 tools. Weights must be a saved frequency or sampling weight; Complex Samples procedures require a survey design approved through define_survey_design.
  • crosstabs connect: a loopback-only connection bridge that hands database tables, query results and CSV-folder files to the crosstabs.com workspace by postMessage (no MCP tool is added).
  • Both servers report package version 1.5.0 through get_runtime_status.

Development

Run Tests

pip install -e ".[dev]"
pytest tests/ -v

Project Structure

mcp-server-python/
├── crosstabs_mcp/
│   ├── __init__.py
│   ├── headless_launcher.py # Node version check and bundled-server launcher
│   ├── headless-mcp.mjs     # Local-first 37-tool workflow MCP server
│   ├── server.py          # Main MCP server
│   ├── market_research.py # Market-research analyses (since 1.5.0)
│   ├── db_connector.py    # Local read-only database pull (since 1.5.0)
│   ├── cli.py             # `crosstabs pull` / `crosstabs connect` subcommands
│   ├── bridge.py          # Loopback connection bridge for crosstabs.com
│   ├── bridge_sources.py  # Bridge source interface: database, CSV folder, survey platforms
│   ├── bridge_static/     # The bridge's own pairing and source page
│   ├── survey_cli.py      # `crosstabs pull <platform>` (since 1.5.0)
│   ├── survey_sources/    # One module per survey platform + shared model/writer
│   └── advanced_stats.py  # Compatibility statistical kernels and contracts
├── tests/
│   ├── test_statistics.py       # Statistical behavior tests
│   ├── test_reference_parity.py # Public SciPy reference parity
│   ├── test_market_research.py  # Market-research tools and website parity
│   ├── test_db_connector.py     # Database pull: SQLite/DuckDB end to end, read-only, limits
│   ├── test_bridge*.py          # Bridge: loopback, Host/Origin checks, pairing, payloads, survey adapter, idle stop
│   └── test_survey_*.py         # Survey pull: recorded platform payloads, .sav round trips
├── scripts/                    # Distribution verification
├── LICENSE
├── pyproject.toml
├── uv.lock
└── README.md

Requirements

  • Python 3.10+
  • mcp >= 1.0.0
  • fastmcp >= 0.1.0
  • numpy >= 1.24.0
  • scipy >= 1.10.0
  • pandas >= 2.0.0
  • statsmodels >= 0.14.0

License

MIT License - see LICENSE for details.

Contributing

The development repository is currently private. Send corrections and proposed changes to support@crosstabs.com.

Metadata

Release files for crosstabs 1.5.3

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for crosstabs 1.5.3
File Size Uploaded Provenance Actions
crosstabs-1.5.3.tar.gz 4.4 MB With provenance Details for crosstabs-1.5.3.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for crosstabs 1.5.3
File Interpreter ABI Platform Actions
crosstabs-1.5.3-py3-none-any.whl Python 3 none any Details for crosstabs-1.5.3-py3-none-any.whl

Total release size: 8.5 MB

Release files / crosstabs-1.5.3.tar.gz

Download URL crosstabs-1.5.3.tar.gz
Size 4.4 MB
Tags Source
SHA-256 checksum
How to use checksums
0273f19f740e688318c48bea2afa318ee3f684f6ad4dd4daeee24271996bb3c6
BLAKE2b-256 checksum
How to use checksums
e073b5dd98a1dbe725fe12b9863dfd498ff93c9b9a20cc14ce903bb3661a7e85
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Release files / crosstabs-1.5.3-py3-none-any.whl

Download URL crosstabs-1.5.3-py3-none-any.whl
Size 4.1 MB
Tags Python 3
SHA-256 checksum
How to use checksums
706e712f4422349cb87fa1de96bf7d52fa5c0aef670639ad573e419859aeffc8
BLAKE2b-256 checksum
How to use checksums
7a539ab6f3fc8ba303343b32417c4e006762d2e5415a7e677c245f9636613bd9
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

Security for crosstabs 1.5.3

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for crosstabs-1.5.3.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 7, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page