Stata Workbench
A VS Code compatible extension (Cursor, Windsurf, Antigravity etc.) that allows Stata code to be run directly from the editor. Enables AI agents to directly interact with Stata. Powered by mcp-stata, https://github.com/tmonk/mcp-stata.
Ask AI about Stata Workbench
Powered by Claude · Grounded in docs
I know everything about Stata Workbench. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
Stata Workbench
Stata Workbench is unified agentic toolkit for Stata development. The toolkit gives AI agents native control over Stata - run commands, inspect variables, export graphs, and build more quickly and reliably than native Stata alone. Built as a VS Code extension (Cursor, Windsurf, Antigravity), so your agent works inside your editor. Powered by mcp-stata. Featured in
News.
Built by Thomas Monk, London School of Economics.
Why use this?
Run Stata without leaving your editor. Execute code, see output, and view graphs - all within VS Code. No switching windows, no copying and pasting between your do-file editor and an AI chat.
For solo work: A modern IDE for Stata—autocomplete, syntax highlighting, multiple cursors, and an AI assistant that can run commands, inspect your variables, and debug errors directly.
For collaboration: Co-authors work in the same environment they use for other code. Shared editor settings, consistent formatting, and AI assistants that understand your project structure.
For teaching: Students learn Stata with the same tools they'll use for everything else - inline errors, an integrated terminal, and an AI that can explain what went wrong.
Installation
Install directly from the marketplace listings by searching for Stata Workbench in the Extensions view.
- VS Code Marketplace: tmonk.stata-workbench
- Open VSX: tmonk/stata-workbench
Offline fallback:
- Download the latest extension .vsix from the releases page.
- In your VS Code/Cursor/Antigravity/Windsurf IDE, open the command palette (
Ctrl+Shift+PorCmd+Shift+Pon Mac) and selectExtensions: Install from VSIX.... - Select the downloaded .vsix file and install.
Quickstart
-
Install the Stata Workbench extension.
-
Open a
.dofile in VS Code (or a compatible editor). -
Run Stata: Run Selection/Line (press the play button on the top right). The Stata Terminal panel opens automatically the first time you run a command. You can interact with this as you would a standard Stata terminal.
-
Run:
sysuse auto, clear summarizeOutput appears as output cards in the panel.
-
Run:
scatter price mpgA Graph artifact card appears - click it to open the generated graph.
-
Open the Data Browser panel to view your data live.
Stata Terminal panel showing output cards and a graph artifact.
Data Browser allows for a live view of your data, with filtering and sorting.
Requirements
- Stata 17+ on macOS, Windows, or Linux.
- uv/uvx: The extension includes bundled
uvbinaries for standard platforms. It will automatically use the systemuvif available on yourPATH, or fall back to the bundled version. No manual installation is required for most users.
Features
Stata Workbench is a unified agentic toolkit for Stata development, providing a rich IDE experience with deep AI integration:
- Integrated Terminal: Rich UI for tracking Stata output with clickable links, integrated search, and persistent history. Provides a Log tab for viewing the full session history with efficient tail-loading.
- Data Browser (
stata-workbench.viewData): High-performance view of millions of rows (~20x faster with Apache Arrow) with live filtering and sorting. - Advanced MCP Tools: Full suite of tools for AI agents (Run, Inspect, Export Graphs, State Diff).
- Run Selection/Current Line (
stata-workbench.runSelection): Executes the selected code or current line via MCP toolrun_commandwith normalized output and graphs. - Run Current File (
stata-workbench.runFile): Runs the entire.dofile via MCP toolrun_do_file. - Environment Detection (
stata_manage_sessionaction="detect"): Returns Stata version, flavor, and OS metadata. - Code Linting (
stata_inspect_dataaction="lint"): Static analysis of.doand.adofiles to identify style violations and potential errors. - Modern Stata Skill: A specialized knowledge base for agents to use frames,
gtools, and other modern Stata features instead of legacy anti-patterns. - Setup Toolkit (
scripts/setup_toolkit.py): Automated registration for Claude Desktop, Codex, VS Code, and Cursor in one command. - Auto-manage MCP configs: Synchronizes your host MCP settings (
mcp.json) across your favorite AI editors. - Status Bar + Cancel (
stata-workbench.cancelRequest): Live request states with one-click cancellation. - Test MCP Server (
stata-workbench.testMcpServer): Quick smoke checks to verify your Stata connection. - Syntax Highlighting: Full support for
.do,.ado,.mata, Dyndoc Markdown, and Dyndoc LaTeX. - Install MCP CLI helper (
stata-workbench.installMcpCli): Bootstrapsuvlocally when it is missing from the environment. - Durable logs: All run results are logged to the
Stata Workbenchoutput channel for persistent reference.
For a detailed breakdown of all capabilities, see FEATURES.md.
Settings
stataMcp.requestTimeoutMs(default100000): timeout for MCP requests.stataMcp.autoRevealOutput(defaultfalse): automatically show the output channel after runs.stataMcp.autoConfigureMcp(defaulttrue): automatically add/update the mcp-stata server entry in your host MCP config (mcp.json).stataMcp.configureClaudeCode(defaultfalse): register mcp-stata viaclaude mcp add-jsonat user scope. Ensures both Claude Code CLI and VS Code extension see the server. Requiresclaudeon PATH.stataMcp.configureCodex(defaultfalse): also configure Codex CLI and VS Code extension MCP settings.stataMcp.codexConfigPath(default~/.codex/config.toml): path to Codex MCP config. Supports~and${workspaceFolder}.stataMcp.runFileWorkingDirectory(default empty): working directory when running .do files. Supports an absolute path, ~, ${workspaceFolder} or ${fileDir}; empty uses the .do file's folder.stataMcp.setupTimeoutSeconds(default60): timeout (seconds) for Stata initialization.stataMcp.noReloadOnClear(defaultfalse): disable reloading startup/profile do files after clear all/program drop.stataMcp.maxOutputLines(default0): limit Stata output to N lines (0 = unlimited). Useful for reducing token usage with AI agents.stataMcp.runFileBehavior(defaultrunDirtyFile): choose whether 'Run File' should run the current editor content (including unsaved changes) or the version saved on disk.stataMcp.defaultVariableLimit(default100): default number of variables to select when opening the Data Browser (0 = all). Useful for huge datasets.
AI Assistant Integration
Automatic Configuration
MCP configuration is synced on extension load and when you toggle the relevant settings. When a setting is enabled, the extension adds or updates the mcp-stata entry in that config. When you turn the setting off, the extension removes the mcp_stata entry cleanly.
| When | Behaviour |
|---|---|
| Extension loads | Adds/updates mcp-stata in each enabled config target |
| Setting toggled ON | Adds/updates mcp-stata in that config |
| Setting toggled OFF | Removes mcp_stata from that config |
The extension detects your editor and writes to the appropriate config file(s).
- User-level
mcp.jsonwith Stata MCP server entry - Uses
uvx --refresh --refresh-package mcp-stata --from mcp-stata@latest mcp-statafor auto-updates - Works for: VS Code, Cursor, Windsurf, Antigravity
- Optional: Claude Code CLI and extension when
stataMcp.configureClaudeCodeis enabled - Optional: Codex CLI and extension when
stataMcp.configureCodexis enabled
Config file locations:
| Editor | macOS | Windows | Linux |
|---|---|---|---|
| VS Code | ~/Library/Application Support/Code/User/mcp.json | %APPDATA%/Code/User/mcp.json | ~/.config/Code/User/mcp.json |
| VS Code Insiders | ~/Library/Application Support/Code - Insiders/User/mcp.json | %APPDATA%/Code - Insiders/User/mcp.json | ~/.config/Code - Insiders/User/mcp.json |
| Cursor | ~/.cursor/mcp.json | %USERPROFILE%/.cursor/mcp.json | ~/.cursor/mcp.json |
| Windsurf | ~/.codeium/windsurf/mcp_config.json | %USERPROFILE%/.codeium/windsurf/mcp_config.json | ~/.codeium/windsurf/mcp_config.json |
| Windsurf Next | ~/.codeium/windsurf-next/mcp_config.json | %USERPROFILE%/.codeium/windsurf-next/mcp_config.json | ~/.codeium/windsurf-next/mcp_config.json |
| Antigravity | ~/Library/Application Support/Antigravity/User/mcp.json | %APPDATA%/Antigravity/User/mcp.json | ~/.antigravity/mcp.json |
| Claude Code CLI & extension | Via claude mcp add-json (user scope) | same | same |
| Codex CLI & extension | stataMcp.codexConfigPath (default ~/.codex/config.toml) | same | same |
If you want to manage the file yourself, here is the content to add. User-level mcp.json:
{
"servers": {
"mcp_stata": {
"type": "stdio",
"command": "uvx",
"args": ["--refresh", "--refresh-package", "mcp-stata", "--from", "mcp-stata@latest", "mcp-stata"]
}
}
}
Troubleshooting
- Claude Code extension doesn't see MCPs: We use
claude mcp add-jsonso both CLI and extension share the same config. Ensureclaudeis on PATH andstataMcp.configureClaudeCodeis enabled. Restart the Claude Code panel after changes. - Icons not visible in editor title bar: If the play, run, and graph icons don't appear when you open a
.dofile, click the...menu in the editor title bar and enable the Stata Workbench icons to make them visible. - Status bar says "CLI missing": This usually only occurs on unsupported platforms where a bundled binary is not provided. Install
uvmanually withcurl -LsSf https://astral.sh/uv/install.sh | sh(macOS/Linux) orpowershell -NoLogo -NoProfile -ExecutionPolicy Bypass -Command "iwr https://astral.sh/uv/install.ps1 -useb | iex"(Windows). - Requests time out: raise
stataMcp.requestTimeoutMs. - Unexpected MCP errors: open the output channel for a structured error message.
- Cancel a stuck run: run
Stata: Cancel Current Requestfrom the command palette.
Uninstall cleanup (optional)
Automatic removal: Turn off stataMcp.autoConfigureMcp, stataMcp.configureClaudeCode, or stataMcp.configureCodex in settings; the extension removes the mcp_stata entry immediately.
Manual removal: Edit the config file and delete the relevant entry:
- VS Code format → delete
servers.mcp_stata - Cursor format → delete
mcpServers.mcp_stata - Claude Code → run
claude mcp remove mcp_stata, or turn offstataMcp.configureClaudeCodeto auto-remove - Codex → delete
[mcp_servers.mcp_stata]and[mcp_servers.mcp_stata.env]from~/.codex/config.toml
Telemetry
This extension uses Sentry to collect error and performance data to improve reliability. No personal data is collected. You can disable telemetry by setting "stata-workbench.telemetry.enabled": false in your VS Code settings.
Acknowledgments
Portions of this file are derived from stata-mcp (MIT License), language-stata by Kyle Barron (MIT License), and vscode-stata by Kyle Butts (MIT License). See license_extras for the full license texts. Do check their projects out!
