Statscraft 0.15.0, release v0.15.0
The MCP server
statscraft mcp lets an AI agent work with Statscraft through tools instead of shell commands. It speaks the Model Context Protocol (MCP) over standard input and output, so any agent app that runs local MCP servers can use it: Claude Desktop, Claude Code, Codex (also in the ChatGPT app), Cursor, VS Code with Copilot and others. It ships with the statscraft command line, so there is nothing more to install, and the data never leave your computer.
The easy way to connect an agent is statscraft connect, which finds the agent apps you have installed and adds Statscraft to each one. Claude Desktop also installs it from a bundle with a double click, and Claude Code from a plugin; see Connect your AI agent. To set one up by hand, give it the command statscraft mcp, with the full path to statscraft if it is not on your PATH.
The tools
| Tool | Input | What it gives back |
|---|---|---|
describe | file (a .sav or .zsav file), or session | the dictionary and counts, and for a session what it keeps; the same JSON as statscraft describe --json |
list_commands | none | every supported command with a one-line summary, as statscraft help |
command_help | command | the syntax, rules and an example of one command, as statscraft help COMMAND |
check_syntax | syntax or file, and optional lines, session, folder, vega_lite | the result of a check, as statscraft check --json; nothing is kept or written |
run_syntax | the same as check_syntax, and optional xlsx; or window (with optional lines) instead of syntax and file | the result of a run, as statscraft run --json; the session keeps the new state, and trail says where its syntax was kept |
window_status | none | whether a Statscraft window is open, and if so its datasets and output documents; also platform (windows, macos, linux) and wsl_distro when the agent runs inside WSL |
list_syntax_windows | none | the syntax windows of the open window: id, name, file, unsaved, lines, and whether it is the Agent window, the designated one or the one the person used last |
read_syntax | window | the text of a syntax window, each line with its number |
edit_syntax | window, mode, text, and lines or before | changes the text: replace the lines lines (an empty text deletes them), insert before line before, append, or replace_all; gives the lines the new text takes |
new_syntax_window | optional name and text | a new syntax window, empty or with the text |
open_syntax_file | path | the .sps file in a syntax window, or the window that has it open already |
save_syntax | window, optional path and overwrite | the window written to its own file or to path |
add_chart | chart, optional session and vega_lite | the chart checked and added to the designated output document, as the result of a run; the text starts with chart added to output document NAME |
syntaxis the text of one or more commands;fileis the absolute path of a .sps file. Give one of them.lineslimits the run to the commands within a line range, such as"12-20". Line numbers stay those of the whole text.folderis the absolute folder that relative file names in the syntax start from. Default: your home folder. Give absolute paths in the syntax to be sure.xlsxalso writes every table and chart of the run to an Excel workbook, one sheet per table; a chart as its data table with an editable chart beside it.vega_liteset to true gives every chart also as a Vega-Lite specification, as--vega-litedoes on the command line.- An agent inside WSL that uses Statscraft on Windows may give Linux paths in the arguments; the server translates them. Inside the syntax, file names must be Windows paths. See Agents inside WSL.
windownames a syntax window of the open window by its id or its name, aslist_syntax_windowsshows them. The syntax window tools work only while the window is open; without it they fail with “no Statscraft window is running”.
A run or check returns the JSON described in the command line as structured content, and the tables and charts as Markdown text with a summary line for apps that show only text. A syntax or run error is a normal result: ok is false and errors gives the line, column and what was expected, so the agent can fix the syntax and try again. A call the server cannot carry out at all, such as a missing file or a bad argument, is marked as a tool error.
The server also sends the working loop to the agent when it connects, and offers it as the prompt analysis: describe the data first, look up each command, check, run in small steps, read ok, errors and the warnings, and report the numbers from the result tables instead of computing them.
Every step leaves syntax
Whatever an agent does through run_syntax stays readable as syntax, so the person can check it, change it and run it again without the agent:
- In the open window, each successful run is added to a syntax window named Agent. It opens with the first run; if the person closes it, the next run opens a new one. Each run comes under a comment line with the time, such as
* Agent 14:32., followed by exactly the syntax that ran. The person can edit it, run lines from it with Ctrl+Enter and save it like any syntax window. Runs sent withstatscraft run -s guifrom the command line go there too. - A run from a syntax window (
run_syntaxwithwindow) is not copied: that window’s text already is its record. - In a file session, each successful run is added to
syntax.spsin the session’s folder, under a comment line with the date and time. - A failed run (
okfalse) changed nothing and leaves nothing; neither does a check. trailin the result, and a linesyntax kept in:in the text, say where the syntax went:syntax window Agent, or the path of the file.
Charts of your own
Procedures draw their own charts. When the person wants a chart that no procedure makes, such as last year’s figures beside this year’s from two runs, add_chart puts it in the output, drawn the Statscraft way:
chartis either the chart JSON thatrun_syntaxreturns undercharts(so an agent can take a procedure’s chart and change its title, labels, kind or numbers), or a simple Vega-Lite specification: one view, the rows inline indata.values, markbar,line,area,pointorarc. Both are described in Charts as input.- The values are drawn as given: nothing is counted, summed or binned. The numbers should come from the result tables.
- In the open window the chart goes to the designated output window, where the person sees it, copies it, opens it in Excel, Word or PowerPoint, and saves or exports it with the other output.
commands[0].documentin the result names the document. - The tool runs the syntax BEGIN CHART, a Statscraft extension, with the chart’s JSON inside. That syntax is kept like any run: in the Agent syntax window, or in
syntax.spsof a file session, so running it again shows the chart again. - A file session keeps no output between calls. To write the chart to a file there, send the BEGIN CHART block and OUTPUT EXPORT or OUTPUT SAVE together through
run_syntax. - A chart that cannot be drawn, a misspelt field, or a Vega-Lite feature that Statscraft does not read is an error to fix, like a syntax error:
okis false and the message names what is wrong. Nothing is added then.
Syntax windows
With the window open, an agent can work in the person’s syntax windows as the person would:
list_syntax_windowsandread_syntaxshow what is there, unsaved changes included. Line numbers are those a run counts.edit_syntaxchanges the text in the editor; the person sees it at once and can take it back with Ctrl+Z in that editor. It never runs anything and writes no file.run_syntaxwithwindowruns the window’s text, or withlinesthe commands those lines touch, exactly as Run and Ctrl+Enter in that window do: relative file names start from the window’s file, and errors are marked in its margin.new_syntax_windowandopen_syntax_fileopen a window; a window an agent opens takes pasted syntax from the dialogs, as a window the person opens does. The Agent window never does.save_syntaxwrites the window to its own file, or topath. It does not replace any other existing file unlessoverwriteis true, and never a file that another syntax window holds.
When the person asks to fix or explain their syntax, the agent reads the window, says what it would change, makes the change with edit_syntax and runs it from the window.
Sessions and the window
A session keeps the data, settings, macros and named datasets between calls, as with statscraft run -s NAME (see sessions).
- When the Statscraft window is open, calls without a
sessiongo to the window (the sessiongui). You see every table appear in the designated output window and every command in the log, and you can keep working in the window between the agent’s steps. - When no window is open, calls without a
sessionuse a session namedwork. - File sessions of the MCP server live in your user data folder, not in the folder the agent app started the server in:
~/.local/share/statscraft/sessionson Linux (or$XDG_DATA_HOME/statscraft/sessions),~/Library/Application Support/Statscraft/sessionson macOS, and%LOCALAPPDATA%\Statscraft\sessionson Windows. Delete a session’s folder for a fresh start, or ask the agent to use a new session name.
Safety
- The server can do what the command line can do, and nothing more. Syntax can read files, and it can write them with
SAVE,AGGREGATE OUTFILE,OUTPUT EXPORTor thexlsxargument.check_syntaxwrites nothing; nothing is written without one of those. - The tools tell the agent app which of them only read (
describe,list_commands,command_help,check_syntax,window_status,list_syntax_windows,read_syntax), which change only the window’s syntax windows (edit_syntax,new_syntax_window,open_syntax_file) or add to its output (add_chart, which writes no file), and thatrun_syntaxandsave_syntaxcan change files. Agent apps ask you before a tool runs, unless you allowed it; allowrun_syntaxonly for agents you trust with your files. - The server talks only to the app that started it, over standard input and output. It opens no network port. Calls to the window use the window’s local connection, described in AI agents.