Skip to content
Back to search

stata-mcp

Stata MCP Extension for VS Code, Cursor, and Antigravity IDE

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hanlulong--stata-mcp/badge.svg)](/listings/hanlulong--stata-mcp)

HTML

<a href="/listings/hanlulong--stata-mcp"><img src="/api/listings/hanlulong--stata-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

> **Note:** Initial installation requires setting up dependencies which may take up to 2 minutes to complete. Please be patient during this one-time setup process. All subsequent runs will start instantly.

1. Open **VS Code**, **Cursor**, or **Antigravity** 2. Open the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`) 3. Search for **"Stata MCP"** 4. Click **Install**

That's it — the extension auto-starts the MCP server and appears in the status bar as **"Stata"**.

<details> <summary><strong>Other installation methods</strong> — CLI, .vsix file, Open VSX</summary>

From the command line

# VS Code
code --install-extension DeepEcon.stata-mcp

# Cursor
cursor --install-extension DeepEcon.stata-mcp

# Antigravity (installs from Open VSX Registry)
antigravity --install-extension DeepEcon.stata-mcp

From a local .vsix file

Download `stata-mcp-<version>.vsix` from the [releases page](https://github.com/hanlulong/stata-mcp/releases), then either:

code        --install-extension path/to/stata-mcp-0.5.3.vsix
cursor      --install-extension path/to/stata-mcp-0.5.3.vsix
antigravity --install-extension path/to/stata-mcp-0.5.3.vsix

…or in the UI: Extensions view → **…** menu → **Install from VSIX…** → pick the downloaded file.

Registries

- VS Code Marketplace: <https://marketplace.visualstudio.com/items?itemName=DeepEcon.stata-mcp> - Open VSX (Cursor / Antigravity): <https://open-vsx.org/extension/DeepEcon/stata-mcp>

</details>

Starting with version 0.1.8, the extension integrates a fast Python package installer called `uv` to set up the environment. If uv is not found on your system, the extension will attempt to install it automatically.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 601 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. # Stata MCP Extension for VS Code, Cursor, and Antigravity
  2. [![en](https://img.shields.io/badge/lang-English-red.svg)](./README.md)
  3. [![cn](https://img.shields.io/badge/语言-中文-yellow.svg)](./README.zh-CN.md)
  4. [![VS Code Marketplace](https://vsmarketplacebadges.dev/version-short/DeepEcon.stata-mcp.svg?label=VS%20Code)](https://marketplace.visualstudio.com/items?itemName=DeepEcon.stata-mcp)
  5. [![VS Code Installs](https://vsmarketplacebadges.dev/installs-short/DeepEcon.stata-mcp.svg?label=VS%20Code%20installs)](https://marketplace.visualstudio.com/items?itemName=DeepEcon.stata-mcp)
  6. [![Open VSX](https://img.shields.io/open-vsx/v/DeepEcon/stata-mcp?label=Open%20VSX)](https://open-vsx.org/extension/DeepEcon/stata-mcp)
  7. [![Open VSX Downloads](https://img.shields.io/open-vsx/dt/DeepEcon/stata-mcp?label=Open%20VSX%20downloads)](https://open-vsx.org/extension/DeepEcon/stata-mcp)
  8. [![GitHub Downloads](https://img.shields.io/github/downloads/hanlulong/stata-mcp/total.svg)](https://github.com/hanlulong/stata-mcp/releases)
  9. [![GitHub License](https://img.shields.io/github/license/hanlulong/stata-mcp)](https://github.com/hanlulong/stata-mcp/blob/main/LICENSE)
  10. This extension provides Stata integration for Visual Studio Code, Cursor, and Antigravity IDE using the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/docs/getting-started/intro). It enables AI-powered Stata development with [GitHub Copilot](https://github.com/features/copilot), [Cursor](https://www.cursor.com/), [Antigravity](https://antigravity.google/), [Cline](https://github.com/cline/cline), [Claude Code](https://claude.com/product/claude-code), or [Codex](https://github.com/openai/codex).
  11. ## Features
  12. - **Run Stata Commands**: Execute selections or entire .do files directly from your editor
  13. - **Real-time Output**: See Stata results instantly in your editor
  14. - **Syntax Highlighting**: Full syntax support for Stata .do, .ado, .mata, and .doh files
  15. - **AI Assistant Integration**: Contextual help and code suggestions via MCP
  16. - **Cross-platform**: Works on Windows, macOS, and Linux
  17. - **Multi-Session Parallel Execution**: Run multiple Stata sessions simultaneously with AI coding tools
  18. ## Demo
  19. Watch how this extension enhances your Stata workflow with Cursor (or VS Code/Antigravity) and AI assistance:
  20. ![Stata MCP Extension Demo](images/demo_2x.gif)
  21. **[🎬 Full Video Version](https://github.com/hanlulong/stata-mcp/raw/main/images/demo.mp4)** &nbsp;&nbsp;|&nbsp;&nbsp; **[📄 View Generated PDF Report](docs/examples/auto_report.pdf)**
  22. <sub>*Demo prompt: "Write and execute Stata do-files, ensuring that full absolute file paths are used in all cases. Load the auto dataset (webuse auto) and generate summary statistics for each variable. Identify and extract key features from the dataset, produce relevant plots, and save them in a folder named plots. Conduct a regression analysis to examine the main determinants of car prices. Export all outputs to a LaTeX file and compile it. Address any compilation errors automatically, and ensure that LaTeX compilation does not exceed 10 seconds. All code errors should be identified and resolved as part of the workflow."*</sub>
  23. ## Requirements
  24. - Stata 17 or higher installed on your machine
  25. - [UV](https://github.com/astral-sh/uv) package manager (automatically installed or can be installed manually if needed)
  26. ## Installation
  27. > **Note:** Initial installation requires setting up dependencies which may take up to 2 minutes to complete. Please be patient during this one-time setup process. All subsequent runs will start instantly.
  28. 1. Open **VS Code**, **Cursor**, or **Antigravity**
  29. 2. Open the Extensions view (`Ctrl+Shift+X` / `Cmd+Shift+X`)
  30. 3. Search for **"Stata MCP"**
  31. 4. Click **Install**
  32. That's it — the extension auto-starts the MCP server and appears in the status bar as **"Stata"**.
  33. <details>
  34. <summary><strong>Other installation methods</strong> — CLI, .vsix file, Open VSX</summary>
  35. #### From the command line
  36. ```bash
  37. # VS Code
  38. code --install-extension DeepEcon.stata-mcp
  39. # Cursor
  40. cursor --install-extension DeepEcon.stata-mcp
  41. # Antigravity (installs from Open VSX Registry)
  42. antigravity --install-extension DeepEcon.stata-mcp
  43. ```
  44. #### From a local .vsix file
  45. Download `stata-mcp-<version>.vsix` from the [releases page](https://github.com/hanlulong/stata-mcp/releases), then either:
  46. ```bash
  47. code --install-extension path/to/stata-mcp-0.5.3.vsix
  48. cursor --install-extension path/to/stata-mcp-0.5.3.vsix
  49. antigravity --install-extension path/to/stata-mcp-0.5.3.vsix
  50. ```
  51. …or in the UI: Extensions view → **…** menu → **Install from VSIX…** → pick the downloaded file.
  52. #### Registries
  53. - VS Code Marketplace: <https://marketplace.visualstudio.com/items?itemName=DeepEcon.stata-mcp>
  54. - Open VSX (Cursor / Antigravity): <https://open-vsx.org/extension/DeepEcon/stata-mcp>
  55. </details>
  56. Starting with version 0.1.8, the extension integrates a fast Python package installer called `uv` to set up the environment. If uv is not found on your system, the extension will attempt to install it automatically.
  57. ## ⚡ Connect Your AI Assistant
  58. Once the extension is running (status bar shows **"Stata"**), the local MCP server is listening on:
  59. - **`http://localhost:4000/mcp-streamable`** — Streamable HTTP (preferred for modern clients)
  60. - `http://localhost:4000/mcp` — SSE (legacy fallback)
  61. Quick health check: `curl -s http://localhost:4000/health` should print a response that includes `"status": "ok"` and `"stata_available": true`. If `stata_available` is `false`, the server is up but Stata failed to load: check the **Stata** output channel (View > Output > Stata).
  62. ### 📋 One-prompt setup
  63. Paste the block below into any MCP-aware assistant — **Claude Code**, **OpenAI Codex**, **Cursor AI**, **Copilot Chat**, etc. Hover the box on GitHub and click the copy icon in the top-right corner.
  64. ```text
  65. Set up the Stata MCP server for me. Endpoint: http://localhost:4000/mcp-streamable — setup guide: https://github.com/hanlulong/stata-mcp#detailed-configurations — if I already have a stata-mcp entry in my MCP config (e.g. using mcp-proxy), replace it rather than appending. When registration succeeds, tell me to restart the client so the stata_run_selection tool becomes available.
  66. ```
  67. The assistant reads the guide, detects which client it is, writes the right config (or runs the right CLI command), and tells you to restart. The `stata_run_selection` tool becomes visible after the restart — MCP tool lists do not refresh mid-session.
  68. Prefer manual setup? Expand **Detailed Configurations** below for per-client instructions.
  69. ## Usage
  70. ### Running Stata Code
  71. 1. Open a Stata .do file
  72. 2. Run commands using:
  73. - **Run Selection**: Select Stata code and press `Ctrl+Shift+Enter` (or `Cmd+Shift+Enter` on Mac), or click the play button in the editor toolbar
  74. - **Run File**: Press `Ctrl+Shift+D` (or `Cmd+Shift+D` on Mac) to run the entire .do file, or click the run-all button in the toolbar
  75. - **Stop Execution**: Press `Ctrl+Shift+C` (or `Cmd+Shift+C` on Mac) to stop a running command
  76. - **Restart Session**: Click the restart button in the editor toolbar or use the Command Palette ("Stata: Restart Session") to reset the Stata session. This clears all in-memory data, globals, and programs — equivalent to closing and reopening Stata
  77. - **Interactive Mode**: Click the graph button in the editor toolbar to run code in an interactive window, shown in a panel (or in your browser, per `stata-vscode.interactiveDisplayMode`)
  78. 3. View output in the Stata Output panel
  79. > **Note for Cursor/Antigravity Users**: Toolbar buttons may be hidden by default. To show them:
  80. > 1. Click the **...** (three dots) menu in the editor title bar
  81. > 2. Select **"Configure Icon Visibility"**
  82. > 3. Enable the Stata buttons you want to see (Run Selection, Run File, Stop, View Data, Restart Session, Interactive)
  83. ### Data Viewer
  84. Access the data viewer to inspect your Stata dataset:
  85. 1. Click the **View Data** button (fourth button, table icon) in the editor toolbar
  86. 2. View your current dataset in a table format
  87. 3. **Filter data**: Use Stata `if` conditions to view subsets of your data
  88. - Example: `price > 5000 & mpg < 30`
  89. - Type your condition in the filter box and click "Apply"
  90. - Click "Clear" to remove the filter and view all data
  91. ### Graph Display Options
  92. Control how graphs are displayed:
  93. 1. **Auto-display graphs**: Graphs are automatically shown when generated (default: enabled)
  94. - Disable in Extension Settings: `stata-vscode.autoDisplayGraphs`
  95. 2. **Choose display method**:
  96. - **VS Code webview** (default): Graphs appear in a panel within VS Code
  97. - **External browser**: Graphs open in your default web browser
  98. - Change in Extension Settings: `stata-vscode.graphDisplayMethod`
  99. ## Detailed Configurations
  100. <details>
  101. <summary><strong>Extension Settings</strong></summary>
  102. Customize the extension behavior through VS Code settings. Access these settings via:
  103. - **VS Code/Cursor/Antigravity**: File > Preferences > Settings (or `Ctrl+,` / `Cmd+,`)
  104. - Search for "Stata MCP" to find all extension settings
  105. ### Core Settings
  106. | Setting | Description | Default |
  107. |---------|-------------|---------|
  108. | `stata-vscode.stataPath` | Path to Stata installation directory | Auto-detected |
  109. | `stata-vscode.stataEdition` | Stata edition to use (MP, SE, BE) | `mp` |
  110. | `stata-vscode.autoStartServer` | Automatically start MCP server when extension activates | `true` |
  111. | `stata-vscode.alwaysShowStatusBar` | Always show the Stata status bar item, even when not editing a Stata file | `true` |
  112. ### Server Settings
  113. | Setting | Description | Default |
  114. |---------|-------------|---------|
  115. | `stata-vscode.mcpServerHost` | Host for MCP server | `localhost` |
  116. | `stata-vscode.mcpServerPort` | Port for the MCP server | `4000` |
  117. | `stata-vscode.forcePort` | Force the specified port even if it's already in use | `false` |
  118. **Keep `mcpServerHost` set to `localhost`.** `0.0.0.0` exposes an unauthenticated server that runs Stata code (including shell commands) to your network. On shared multi-user machines (for example HPC login nodes over Remote-SSH), other users of that machine can also reach `localhost:4000`, so turn `stata-vscode.autoStartServer` off there.
  119. ### Graph Settings
  120. | Setting | Description | Default |
  121. |---------|-------------|---------|
  122. | `stata-vscode.autoDisplayGraphs` | Automatically display graphs when generated by Stata commands | `true` |
  123. | `stata-vscode.graphDisplayMethod` | Choose how to display graphs: `vscode` (webview panel) or `browser` (external browser) | `vscode` |
  124. | `stata-vscode.interactiveDisplayMode` | Where the Interactive Window opens: `panel` (webview panel) or `browser` (external browser) | `panel` |
  125. ### Log File Settings
  126. | Setting | Description | Default |
  127. |---------|-------------|---------|
  128. | `stata-vscode.logFileLocation` | Location for Stata log files: `dofile` (same directory as .do file), `parent` (parent directory of .do file), `workspace` (VS Code workspace root), `extension` (logs folder in extension directory), or `custom` (user-specified directory) | `extension` |
  129. | `stata-vscode.customLogDirectory` | Custom directory for Stata log files (only used when logFileLocation is set to `custom`) | Empty |
  130. ### Advanced Settings
  131. | Setting | Description | Default |
  132. |---------|-------------|---------|
  133. | `stata-vscode.runFileTimeout` | Timeout in seconds for 'Run File' operations | `600` (10 minutes) |
  134. | `stata-vscode.runSelectionTimeout` | Timeout in seconds for 'Run Selection' and interactive window commands | `600` (10 minutes) |
  135. | `stata-vscode.debugMode` | Show detailed debug information in output panel | `false` |
  136. | `stata-vscode.dataViewerMaxRows` | Maximum number of rows the Data Viewer loads (100-500000) | `100000` |
  137. ### Working Directory Settings
  138. Control which directory Stata uses when running .do files:
  139. | Setting | Description | Default |
  140. |---------|-------------|---------|
  141. | `stata-vscode.workingDirectory` | Working directory when running .do files: `dofile` (same as .do file), `parent` (parent directory of .do file), `workspace` (VS Code workspace root), `extension` (logs folder in extension directory), `custom` (user-specified), or `none` (don't change directory) | `dofile` |
  142. | `stata-vscode.customWorkingDirectory` | Custom working directory path (only used when workingDirectory is set to `custom`) | Empty |
  143. **Example:** If your project structure is `project/code/analysis.do` and your do-file expects to run from `project/`, set `workingDirectory` to `parent`.
  144. ### MCP Output Settings
  145. These settings control how Stata output is returned to AI assistants (LLMs) via the MCP protocol, helping to reduce token usage:
  146. | Setting | Description | Default |
  147. |---------|-------------|---------|
  148. | `stata-vscode.resultDisplayMode` | Output mode for MCP returns: `compact` (filters redundant output to save tokens) or `full` (returns complete output) | `compact` |
  149. | `stata-vscode.maxOutputTokens` | Maximum tokens for MCP output (0 = unlimited). Large outputs are saved to file with a path returned instead | `10000` |
  150. **Compact mode filters:**
  151. - Loop code echoes (foreach/forvalues/while blocks) - keeps actual output only
  152. - Program definitions and Mata blocks
  153. - Command echoes and line continuations (for `run_file` only)
  154. - Verbose messages like "(N real changes made)" and "(N missing values generated)"
  155. ### Multi-Session Settings
  156. Enable parallel Stata execution with isolated sessions. Each session has its own data, variables, and macros.
  157. | Setting | Description | Default |
  158. |---------|-------------|---------|
  159. | `stata-vscode.multiSession` | Enable multi-session mode for parallel Stata execution | `true` |
  160. | `stata-vscode.maxSessions` | Maximum number of concurrent sessions (1-100) | `100` |
  161. | `stata-vscode.sessionTimeout` | Session idle timeout in seconds. Sessions are automatically destroyed after this period of inactivity | `3600` |
  162. **Note:** Each session requires ~200-300 MB RAM for Stata. Check your Stata license for concurrent instance limits.
  163. <br>
  164. </details>
  165. <details>
  166. <summary><strong>GitHub Copilot</strong></summary>
  167. [GitHub Copilot](https://github.com/features/copilot) supports MCP (Model Context Protocol) starting from VS Code 1.102. You can connect the Stata MCP server to Copilot for AI-powered Stata development.
  168. ### Configuration
  169. 1. **Install the Stata MCP extension** in VS Code (see [Installation](#installation) section above)
  170. 2. **Start the Stata MCP server**: The server should start automatically when you open VS Code with the extension installed. Verify it's running by checking the status bar (should show "Stata").
  171. 3. **Add the Stata MCP server to Copilot**: You can configure MCP servers either per-workspace or globally.
  172. **Option A: Per-Workspace Configuration**
  173. Create a `.vscode/mcp.json` file in your workspace root:
  174. ```json
  175. {
  176. "servers": {
  177. "stata-mcp": {
  178. "type": "http",
  179. "url": "http://localhost:4000/mcp-streamable"
  180. }
  181. }
  182. }
  183. ```
  184. **Option B: Global Configuration (All Workspaces)**
  185. 1. Open Command Palette (Ctrl+Shift+P / Cmd+Shift+P)
  186. 2. Type **"MCP: Open User Configuration"** and select it
  187. 3. Add the Stata MCP server to the `mcp.json` file:
  188. ```json
  189. {
  190. "servers": {
  191. "stata-mcp": {
  192. "type": "http",
  193. "url": "http://localhost:4000/mcp-streamable"
  194. }
  195. }
  196. }
  197. ```
  198. > On older VS Code versions without Streamable HTTP support, use `"type": "sse"` with `http://localhost:4000/mcp` instead.
  199. The user-level `mcp.json` file is located at:
  200. - **Windows**: `%APPDATA%\Code\User\mcp.json`
  201. - **macOS**: `~/Library/Application Support/Code/User/mcp.json`
  202. - **Linux**: `~/.config/Code/User/mcp.json`
  203. 4. **Reload VS Code** to apply the configuration.
  204. 5. GitHub Copilot will now have access to Stata tools and can help you:
  205. - Write and execute Stata commands
  206. - Analyze your data
  207. - Generate visualizations
  208. - Debug Stata code
  209. - Create statistical reports
  210. ### Verifying the Connection
  211. 1. Open GitHub Copilot Chat (Ctrl+Shift+I / Cmd+Shift+I)
  212. 2. Open **Configure Tools** in the chat input
  213. 3. Check that stata-mcp's tools (`stata_run_selection`, `stata_run_file`, and `stata_session` over Streamable HTTP) are listed
  214. ### Troubleshooting
  215. If Copilot is not recognizing the Stata MCP server:
  216. 1. Verify VS Code version 1.102 or later
  217. 2. Verify the MCP server is running (Status bar should show "Stata")
  218. 3. Check that `.vscode/mcp.json` exists with the correct content
  219. 4. Try restarting VS Code
  220. 5. Check the extension output panel (View > Output > Stata) for any errors
  221. 6. Ensure MCP is enabled in your organization's Copilot policy (if applicable)
  222. <br>
  223. </details>
  224. <details>
  225. <summary><strong>Claude Code</strong></summary>
  226. [Claude Code](https://claude.com/product/claude-code) is Anthropic's official AI coding assistant available in VS Code, Cursor, and Antigravity. Follow these steps to configure the Stata MCP server:
  227. ### Installation
  228. 1. **Install the Stata MCP extension** in VS Code, Cursor, or Antigravity (see [Installation](#installation) section above)
  229. 2. **Start the Stata MCP server**: The server should start automatically when you open your IDE with the extension installed. Verify it's running by checking the status bar (should show "Stata").
  230. ### Configuration
  231. Once the Stata MCP server is running, configure Claude Code to connect to it:
  232. 1. Open your terminal or command palette
  233. 2. Run the following command to add the Stata MCP server:
  234. ```bash
  235. claude mcp add --transport http stata-mcp http://localhost:4000/mcp-streamable --scope user
  236. ```
  237. > Claude Code versions older than 1.0.27 (June 2025) may not recognize `--transport http`. On those, use `--transport sse` with `http://localhost:4000/mcp` instead. Claude Code now treats SSE as legacy — prefer `http` whenever it is supported.
  238. 3. Restart your IDE
  239. 4. Claude Code will now have access to Stata tools and can help you:
  240. - Write and execute Stata commands
  241. - Analyze your data
  242. - Generate visualizations
  243. - Debug Stata code
  244. - Create statistical reports
  245. ### Verifying the Connection
  246. To verify Claude Code is properly connected to the Stata MCP server:
  247. 1. Open a Stata .do file or create a new one
  248. 2. Ask Claude Code to help with a Stata task (e.g., "Load the auto dataset and show summary statistics")
  249. 3. Claude Code should be able to execute Stata commands and show results
  250. ### Troubleshooting
  251. If Claude Code is not recognizing the Stata MCP server:
  252. 1. Verify the MCP server is running (Status bar should show "Stata")
  253. 2. Check that you ran the `claude mcp add` command with the correct URL
  254. 3. Try restarting your IDE
  255. 4. Check the extension output panel (View > Output > Stata) for any errors
  256. 5. Ensure there are no port conflicts (default port is 4000)
  257. <br>
  258. </details>
  259. <details>
  260. <summary><strong>Claude Desktop</strong></summary>
  261. [Claude Desktop](https://claude.ai/download) can use the extension's local MCP server through `claude_desktop_config.json`. Make sure the Stata MCP extension is installed and its status bar shows **"Stata"** before configuring Claude Desktop.
  262. Claude Desktop's JSON config doesn't accept remote URLs directly, so you need a local stdio wrapper. The easiest is [`mcp-remote`](https://www.npmjs.com/package/mcp-remote), which runs through `npx` if you have [Node.js](https://nodejs.org/):
  263. 1. Open the config file from Claude Desktop → **Settings** → **Developer** → **Edit Config**, or open it directly:
  264. - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
  265. - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
  266. 2. Add this block (merge with any existing `mcpServers` object):
  267. ```json
  268. {
  269. "mcpServers": {
  270. "stata-mcp": {
  271. "command": "npx",
  272. "args": ["-y", "mcp-remote", "http://localhost:4000/mcp-streamable"]
  273. }
  274. }
  275. }
  276. ```
  277. 3. Fully quit and restart Claude Desktop. The Stata tools will appear in the available-tools list.
  278. > **Note:** don't add this server with **Settings** → **Connectors** → **Add custom connector**. Custom connectors only accept `https://` URLs of internet-hosted servers, so they can't reach the local `http://localhost:4000` server.
  279. If the tools don't show up, check that `curl -s http://localhost:4000/health` responds with `"status": "ok"` and `"stata_available": true` (`false` means the server is up but Stata failed to load; see the **Stata** output channel), then look at Claude Desktop's MCP logs (`~/Library/Logs/Claude/mcp-server-stata-mcp.log` on macOS, `%APPDATA%\Claude\logs\mcp-server-stata-mcp.log` on Windows).
  280. <br>
  281. </details>
  282. <details>
  283. <summary><strong>OpenAI Codex</strong></summary>
  284. You can use this extension with [OpenAI Codex](https://github.com/openai/codex) — the CLI and every IDE extension share the same `~/.codex/config.toml`. Codex CLI **0.46.0+** (October 2025) connects to HTTP MCP servers directly, without a wrapper (0.46.x needed one extra flag; see Troubleshooting below). Either drive it from the command line:
  285. ```bash
  286. codex mcp add stata-mcp --url http://localhost:4000/mcp-streamable
  287. ```
  288. Then add `tool_timeout_sec = 900` under the `[mcp_servers.stata-mcp]` block that this command writes to `~/.codex/config.toml` (see below).
  289. Or append this block manually to `~/.codex/config.toml` (or `%USERPROFILE%\.codex\config.toml` on Windows):
  290. ```toml
  291. [mcp_servers.stata-mcp]
  292. url = "http://localhost:4000/mcp-streamable"
  293. tool_timeout_sec = 900
  294. ```
  295. Codex's default per-tool timeout (60 s in early releases, 300 s in current ones) is shorter than the server's default 600-second run limit, so raise it to keep long Stata runs from being cut off.
  296. > **Upgrading from an older setup?** If an existing `[mcp_servers.stata-mcp]` block uses `command = "mcp-proxy"` (or `command = "uvx"` + `mcp-proxy` in args), **delete that block** before adding the one above — TOML forbids duplicate keys, and Codex will silently skip the server if both are present.
  297. Then restart Codex — the `stata_run_selection`, `stata_run_file` and `stata_session` tools will appear. Run `codex mcp list` to confirm the server is registered.
  298. > **Note on transports.** Codex only speaks MCP's *Streamable HTTP* transport (single endpoint at `/mcp-streamable`). The extension's legacy SSE endpoint (`/mcp`) is for older clients like GitHub Copilot — don't point Codex at it.
  299. ### Troubleshooting Codex Configuration
  300. If Codex doesn't see the Stata tools:
  301. 1. Verify the MCP server is running (status bar shows "Stata") — try `curl -s http://localhost:4000/health`; the response should include `"status": "ok"` and `"stata_available": true` (`false` means Stata failed to load; check the *Stata* output channel)
  302. 2. Check `codex --version` — make sure you're on **0.46.0** or newer. Older Codex versions need the `mcp-proxy` wrapper (see note below).
  303. On early HTTP-capable releases (0.46.x), Codex also needed `experimental_use_rmcp_client = true` at the top level of `config.toml`; if the server doesn't load on such a release, add it or update Codex.
  304. 3. Verify the config file exists at `~/.codex/config.toml` and contains the exact `[mcp_servers.stata-mcp]` block above
  305. 4. Run `codex mcp list` — `stata-mcp` should appear as registered
  306. 5. Restart Codex (CLI or IDE) after config changes
  307. 6. Check the extension output panel (View → Output → *Stata*) for any server-side errors
  308. 7. Ensure no port conflict (default is 4000 — change via `stata-vscode.mcpServerPort` if needed)
  309. <details>
  310. <summary>Stuck on Codex &lt; 0.46.0?</summary>
  311. If you cannot upgrade, use [`mcp-proxy`](https://github.com/sparfenyuk/mcp-proxy) as a stdio wrapper around the SSE endpoint:
  312. ```bash
  313. # Install uv first if needed:
  314. curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux
  315. # Windows: powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
  316. ```
  317. ```toml
  318. [mcp_servers.stata-mcp]
  319. command = "uvx"
  320. args = ["mcp-proxy", "http://localhost:4000/mcp"]
  321. ```
  322. </details>
  323. <br>
  324. </details>
  325. <details>
  326. <summary><strong>Cline</strong></summary>
  327. 1. Open your [Cline](https://github.com/cline/cline) MCP settings file. The easiest way: in the Cline panel, click the **MCP Servers** icon, open the **Configure** tab and click **Configure MCP Servers**. This opens the file your Cline version uses:
  328. - **Newer Cline builds** (shown as "Next" next to the version in Cline's Settings > About) and the Cline CLI: `~/.cline/data/settings/cline_mcp_settings.json` (on Windows, `%USERPROFILE%\.cline\data\settings\cline_mcp_settings.json`)
  329. - **Older Cline builds** (or "Legacy" in Settings > About):
  330. - **macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  331. - **Windows**: `%APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  332. - **Linux**: `~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
  333. 2. Add the Stata MCP server configuration:
  334. ```json
  335. {
  336. "mcpServers": {
  337. "stata-mcp": {
  338. "type": "streamableHttp",
  339. "url": "http://localhost:4000/mcp-streamable"
  340. }
  341. }
  342. }
  343. ```
  344. Keep the `"type": "streamableHttp"` line: without a `type`, Cline uses the legacy SSE transport. To use SSE instead, set `"type": "sse"` with `http://localhost:4000/mcp`.
  345. 3. If the file already contains other MCP servers, just add the `"stata-mcp"` entry to the existing `"mcpServers"` object.
  346. 4. Save the file and restart VS Code.
  347. > **Set up stata-mcp in Cline earlier without a `type` field?** Cline treats that entry as SSE, which fails against `/mcp-streamable`. Open the settings file as in step 1 and set `"type": "streamableHttp"` on the `stata-mcp` entry. Newer ("Next") Cline builds copy old entries once into `~/.cline/data/settings/cline_mcp_settings.json` and stop reading the old globalStorage file after that, so edit the new file; a copied entry may look like `"transport": { "type": "sse", ... }`, in which case change that `type` to `"streamableHttp"`.
  348. ### Troubleshooting Cline Configuration
  349. If Cline is not recognizing the Stata MCP server:
  350. 1. Verify the MCP server is running (Status bar should show "Stata")
  351. 2. Check that the configuration file exists with the correct content
  352. 3. Try restarting VS Code
  353. 4. Check the extension output panel (View > Output > Stata) for any errors
  354. <br>
  355. </details>
  356. <details>
  357. <summary><strong>Cursor</strong></summary>
  358. The extension automatically configures [Cursor](https://www.cursor.com/) MCP integration. To verify it's working:
  359. 1. Open Cursor
  360. 2. Press `Ctrl+Shift+P` (or `Cmd+Shift+P` on Mac) to open the Command Palette
  361. 3. Type "Stata: Test MCP Server Connection" and press Enter
  362. 4. You should see a success message if the server is properly connected
  363. ### Cursor Configuration File Paths
  364. Cursor reads user-level MCP config from:
  365. - **macOS / Linux**: `~/.cursor/mcp.json`
  366. - **Windows**: `%USERPROFILE%\.cursor\mcp.json`
  367. Workspace-level config (overrides user-level for that project) goes in `.cursor/mcp.json` at the workspace root.
  368. ### Manual Cursor Configuration
  369. If you need to manually configure Cursor MCP:
  370. 1. Create or edit the MCP configuration file:
  371. - **macOS/Linux**: `~/.cursor/mcp.json`
  372. - **Windows**: `%USERPROFILE%\.cursor\mcp.json`
  373. 2. Add the Stata MCP server configuration:
  374. ```json
  375. {
  376. "mcpServers": {
  377. "stata-mcp": {
  378. "url": "http://localhost:4000/mcp-streamable"
  379. }
  380. }
  381. }
  382. ```
  383. Cursor auto-detects the transport from the URL — no `transport` key needed. It tries Streamable HTTP first and falls back to SSE if the server advertises it.
  384. 3. If the file already contains other MCP servers, just add the `"stata-mcp"` entry to the existing `"mcpServers"` object.
  385. 4. Save the file and restart Cursor.
  386. ### Troubleshooting Cursor Configuration
  387. If Cursor is not recognizing the Stata MCP server:
  388. 1. Verify the MCP server is running
  389. 2. Check that the configuration file exists with the correct content
  390. 3. Try restarting Cursor
  391. 4. Ensure there are no port conflicts with other running applications
  392. <br>
  393. </details>
  394. <details>
  395. <summary><strong>Python Environment Management</strong></summary>
  396. This extension uses [uv](https://github.com/astral-sh/uv), a fast Python package installer built in Rust, to manage Python dependencies. Key features:
  397. - Automatic Python setup and dependency management
  398. - Creates isolated environments that won't conflict with your system
  399. - Works across Windows, macOS, and Linux
  400. - 10-100x faster than traditional pip installations
  401. **If you encounter any UV-related errors during installation:**
  402. 1. Install UV manually:
  403. ```bash
  404. # Windows (PowerShell as Administrator)
  405. powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  406. # macOS/Linux
  407. curl -LsSf https://astral.sh/uv/install.sh | sh
  408. ```
  409. 2. Follow the [clean-reinstall steps in the troubleshooting guide](docs/troubleshooting.md) to reinstall the extension.
  410. <br>
  411. </details>
  412. ## Troubleshooting
  413. Running into trouble? The full troubleshooting guide — clean reinstall steps for Windows / macOS / Linux, common Python and UV issues, Stata-edition mismatches, and what to include when opening a GitHub issue — lives in [docs/troubleshooting.md](docs/troubleshooting.md).
  414. ## Star History
  415. [![Star History Chart](https://api.star-history.com/svg?repos=hanlulong/stata-mcp&type=Date)](https://star-history.com/#hanlulong/stata-mcp&Date)
  416. ## License
  417. MIT
  418. ## Credits
  419. Created by Lu Han,
  420. Published by [OpenEcon.ai](https://openecon.ai/)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.