Stata Workbench

A VS Code compatible extension (Cursor, Windsurf, Antigravity etc.) that runs Stata directly from your editor that allows Stata code to be run directly from the editor. Enables AI agents to directly interact with Stata, powered by mcp-stata.

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/VSIX fallback:

1. Download the latest extension .vsix from the releases page.
2. In your VS Code/Cursor/Antigravity/Windsurf IDE, open the command palette (Ctrl+Shift+P or Cmd+Shift+P on Mac) and select Extensions: Install from VSIX....
3. Select the downloaded .vsix file and install.

Quickstart

1. Install the Stata Workbench extension.

2. Open a .do file in VS Code (or a compatible editor).

3. 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.

4. Run:

   sysuse auto, clear
   summarize

   Output appears as “Stata Output” cards (with return code + timing) in the panel.

5. Run:

   scatter price mpg

   A Graph artifact card appears - click it to open the generated graph.

Requirements

• Stata 17+ on Mac OS, Windows, or Linux.
• uv/uvx on PATH (to run the published mcp-stata tool). If missing, the extension automatically bootstraps uv locally into its storage.

Features & Commands

• Syntax highlighting for Stata, Dyndoc Markdown, and Dyndoc LaTeX.
• Run Selection/Current Line (stata-workbench.runSelection) → Executes the selected code or current line via MCP tool run_command with normalized output + graphs. Results appear in the terminal panel.
• Run Current File (stata-workbench.runFile) → Runs the entire .do file via MCP tool run_do_file. Results appear in the terminal panel.
• Terminal panel: Automatically opens when running code, displaying results with stdout/stderr, execution time, return codes, and graph artifacts. You can continue running additional Stata commands directly in the panel. Supports quick history navigation (PageUp/PageDown) and Tab-based variable name completion sourced from the active Stata dataset.
• Graph viewer (stata-workbench.showGraphs): View all graphs from the current Stata session via list_graphs and export_graph MCP tools. Click any graph to open it.
• Test MCP Server (stata-workbench.testMcpServer) for quick smoke checks.
• Install MCP CLI helper (stata-workbench.installMcpCli): Bootstraps uv locally when it is missing.
• Status bar + cancel (stata-workbench.cancelRequest): Live request states with one-click cancellation routed through the MCP client.
• Auto-manage MCP configs: Writes the user-level mcp.json in your editor's user data so AI agents reuse the same uvx --from mcp-stata --refresh mcp-stata wiring, and auto-corrects older entries missing --refresh.
• Durable logs: All run results are logged to the Stata Workbench output channel for reference.

Settings

• stataMcp.requestTimeoutMs (default 45000): timeout for MCP requests.
• stataMcp.autoRevealOutput (default true): automatically show the output channel after runs.
• stataMcp.runFileWorkingDirectory (default empty): working directory when running .do files. Supports an absolute path, ~, ${workspaceFolder} or ${fileDir}; empty uses the .do file's folder.

Agent MCP configs (optional)

When uv is available, the extension writes a user-level mcp.json inside your editor's user data. Example locations:

• macOS: VS Code ~/Library/Application Support/Code/User/mcp.json; VS Code Insiders ~/Library/Application Support/Code - Insiders/User/mcp.json; Cursor ~/.cursor/mcp.json; Windsurf ~/.codeium/mcp_config.json; Antigravity ~/Library/Application Support/Antigravity/User/mcp.json
• Windows: VS Code %APPDATA%/Code/User/mcp.json; VS Code Insiders %APPDATA%/Code - Insiders/User/mcp.json; Cursor %USERPROFILE%/.cursor/mcp.json; Windsurf %USERPROFILE%/.codeium/mcp_config.json; Antigravity %APPDATA%/Antigravity/User/mcp.json
• Linux: VS Code ~/.config/Code/User/mcp.json; VS Code Insiders ~/.config/Code - Insiders/User/mcp.json; Cursor ~/.cursor/mcp.json; Windsurf ~/.codeium/mcp_config.json; Antigravity ~/.antigravity/mcp.json

If you want to manage the file yourself, use the snippets below.

User-level mcp.json:

{
  "servers": {
    "mcp_stata": {
      "type": "stdio",
      "command": "uvx",
      "args": ["--from", "mcp-stata", "mcp-stata", "--refresh"]
    }
  }
}

Troubleshooting

• Icons not visible in editor title bar: If the play, run, and graph icons don't appear when you open a .do file, click the ... menu in the editor title bar and enable the Stata Workbench icons to make them visible.
• Status bar says "CLI missing": install uv (includes uvx) with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -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 Request from the command palette.

Uninstall cleanup (optional)

If you added agent configs and want to remove them, edit your user-level mcp.json (same path as above) and delete the relevant entry:

• VS Code format → delete servers.mcp_stata
• Cursor format → delete mcpServers.mcp_stata

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!