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.