Stata MCP Extension for VS Code and Cursor

This extension provides Stata integration for Visual Studio Code and Cursor IDE using the Model Context Protocol (MCP).

The extension allows you to:

Run Stata commands directly from VS Code or Cursor
Execute selections or entire .do files
View Stata output in the editor in real-time
Get AI assistant integration through the MCP protocol
Experience enhanced AI coding with Cursor, Cline, Claude Code, or Codex
Choose your Stata edition (MP, SE, or BE)

Features

Run Stata Commands: Execute selections or entire .do files directly from your editor
Syntax Highlighting: Full syntax support for Stata .do, .ado, .mata, and .doh files
AI Assistant Integration: Contextual help and code suggestions via MCP
Cross-platform: Works on Windows, macOS, and Linux
Automatic Stata Detection: Automatically finds your Stata installation
Real-time Output: See Stata results instantly in your editor

Demo

Watch how this extension enhances your Stata workflow with Cursor (or VS Code) and AI assistance:

Stata MCP Extension Demo

🎬 Full Video Version | 📄 View Generated PDF Report

_{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."}

Looking for other Stata integrations?

Use Stata with Notepad++ and Sublime Text 3? See here

Use Stata via Jupyter? See here

Requirements

Stata 17 or higher installed on your machine
UV package manager (automatically installed or can be installed manually if needed)

Installation

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.

VS Code Installation

Option 1: From VS Code Marketplace

Install this extension directly from the VS Code Marketplace.

code --install-extension DeepEcon.stata-mcp

Or:

Open VS Code
Go to Extensions view (Ctrl+Shift+X)
Search for "Stata MCP"
Click "Install"

Option 2: From .vsix file

Download the extension package stata-mcp-0.3.5.vsix from the releases page.
Install using one of these methods:

code --install-extension path/to/stata-mcp-0.3.5.vsix

Or:

Open VS Code
Go to Extensions view (Ctrl+Shift+X)
Click on "..." menu in the top-right
Select "Install from VSIX..."
Navigate to and select the downloaded .vsix file

Cursor Installation

Download the extension package stata-mcp-0.3.5.vsix from the releases page.
Install using one of these methods:

cursor --install-extension path/to/stata-mcp-0.3.5.vsix

Or:

Open Cursor
Go to Extensions view
Click on the "..." menu
Select "Install from VSIX"
Navigate to and select the downloaded .vsix file

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.

Usage

Running Stata Code

Open a Stata .do file
Run commands using:
- Run Selection: Select Stata code and press Ctrl+Shift+Enter (or Cmd+Shift+Enter on Mac), or click the first button (▶️) in the editor toolbar
- Run File: Press Ctrl+Shift+D (or Cmd+Shift+D on Mac) to run the entire .do file, or click the second button in the toolbar
- Interactive Mode: Select Stata code and click the 📊 button in the editor toolbar to run the selection in an interactive window, or click without selection to run the entire file
View output in the editor panel or interactive window

Data Viewer

Access the data viewer to inspect your Stata dataset:

Click the View Data button (fourth button, table icon) in the editor toolbar
View your current dataset in a table format
Filter data: Use Stata if conditions to view subsets of your data
- Example: price > 5000 & mpg < 30
- Type your condition in the filter box and click "Apply"
- Click "Clear" to remove the filter and view all data

Graph Display Options

Control how graphs are displayed:

Auto-display graphs: Graphs are automatically shown when generated (default: enabled)
- Disable in Extension Settings: stata-vscode.autoDisplayGraphs
Choose display method:
- VS Code webview (default): Graphs appear in a panel within VS Code
- External browser: Graphs open in your default web browser
- Change in Extension Settings: stata-vscode.graphDisplayMethod

Stata Edition Selection

Select your preferred Stata edition (MP, SE, or BE) in the Extension Settings

Detailed Configurations

Extension Settings

Customize the extension behavior through VS Code settings. Access these settings via:

VS Code/Cursor: File > Preferences > Settings (or Ctrl+, / Cmd+,)
Search for "Stata MCP" to find all extension settings

Core Settings

Setting	Description	Default
`stata-vscode.stataPath`	Path to Stata installation directory	Auto-detected
`stata-vscode.stataEdition`	Stata edition to use (MP, SE, BE)	`mp`
`stata-vscode.autoStartServer`	Automatically start MCP server when extension activates	`true`

Server Settings

Setting	Description	Default
`stata-vscode.mcpServerHost`	Host for MCP server	`localhost`
`stata-vscode.mcpServerPort`	Port for the MCP server	`4000`
`stata-vscode.forcePort`	Force the specified port even if it's already in use	`false`

Graph Settings

Setting	Description	Default
`stata-vscode.autoDisplayGraphs`	Automatically display graphs when generated by Stata commands	`true`
`stata-vscode.graphDisplayMethod`	Choose how to display graphs: `vscode` (webview panel) or `browser` (external browser)	`vscode`

Log File Settings

Setting	Description	Default
`stata-vscode.logFileLocation`	Location for Stata log files: `extension` (logs folder in extension directory), `workspace` (same directory as .do file), or `custom` (user-specified directory)	`extension`
`stata-vscode.customLogDirectory`	Custom directory for Stata log files (only used when logFileLocation is set to `custom`)	Empty

Advanced Settings

Setting	Description	Default
`stata-vscode.runFileTimeout`	Timeout in seconds for 'Run File' operations	`600` (10 minutes)
`stata-vscode.debugMode`	Show detailed debug information in output panel	`false`
`stata-vscode.clineConfigPath`	Custom path to Cline configuration file (optional)	Auto-detected

How to Change Settings

Open VS Code/Cursor settings (Ctrl+, or Cmd+,)
Search for "Stata MCP"
Modify the desired settings
Restart the extension or reload the window if prompted

Log File Management

The extension automatically creates log files when running Stata .do files. You can control where these log files are saved:

Log File Locations

Extension Directory (default): Log files are saved in a logs folder within the extension directory, keeping your workspace clean
Workspace Directory: Log files are saved in the same directory as your .do file (original behavior)
Custom Directory: Log files are saved to a directory you specify

Changing Log File Location

Open VS Code/Cursor settings (Ctrl+, or Cmd+,)
Search for "Stata MCP"
Find "Log File Location" (stata-vscode.logFileLocation) and select your preferred option:
- extension: Save to extension directory (default)
- workspace: Save to same directory as .do file
- custom: Save to a custom directory
If using "Custom Directory", also set "Custom Log Directory" (stata-vscode.customLogDirectory) path

Benefits of Each Option

Extension Directory: Keeps your project workspace clean and organized
Workspace Directory: Log files stay with your .do files for easy reference
Custom Directory: Centralize all logs in one location across projects

Claude Code

Claude Code is Anthropic's official AI coding assistant available in VS Code and Cursor. Follow these steps to configure the Stata MCP server:

Installation

Install the Stata MCP extension in VS Code or Cursor (see Installation section above)
Start the Stata MCP server: The server should start automatically when you open VS Code/Cursor with the extension installed. Verify it's running by checking the status bar (should show "Stata").

Configuration

Once the Stata MCP server is running, configure Claude Code to connect to it:

Open your terminal or command palette

Run the following command to add the Stata MCP server:

claude mcp add --transport sse stata-mcp http://localhost:4000/mcp --scope user

Restart VS Code or Cursor
Claude Code will now have access to Stata tools and can help you:
- Write and execute Stata commands
- Analyze your data
- Generate visualizations
- Debug Stata code
- Create statistical reports

Verifying the Connection

To verify Claude Code is properly connected to the Stata MCP server:

Open a Stata .do file or create a new one
Ask Claude Code to help with a Stata task (e.g., "Load the auto dataset and show summary statistics")
Claude Code should be able to execute Stata commands and show results

Troubleshooting

If Claude Code is not recognizing the Stata MCP server:

Verify the MCP server is running (Status bar should show "Stata")
Check that you ran the claude mcp add command with the correct URL
Try restarting VS Code or Cursor
Check the extension output panel (View > Output > Stata MCP) for any errors
Ensure there are no port conflicts (default port is 4000)

Claude Desktop

You can use this extension with Claude Desktop through mcp-proxy:

Make sure the Stata MCP extension is installed in VS Code or Cursor and currently running before attempting to configure Claude Desktop

Install mcp-proxy:

# Using pip
pip install mcp-proxy

# Or using uv (faster)
uv install mcp-proxy

Find the path to mcp-proxy:

# On Mac/Linux
which mcp-proxy

# On Windows (PowerShell)
(Get-Command mcp-proxy).Path

Configure Claude Desktop by editing the MCP config file:

On Windows (typically at %APPDATA%\Claude Desktop\claude_desktop_config.json):

{
  "mcpServers": {
    "stata-mcp": {
      "command": "mcp-proxy",
      "args": ["http://127.0.0.1:4000/mcp"]
    }
  }
}

On macOS (typically at ~/Library/Application Support/Claude Desktop/claude_desktop_config.json):

{
  "mcpServers": {
    "stata-mcp": {
      "command": "/path/to/mcp-proxy",
      "args": ["http://127.0.0.1:4000/mcp"]
    }
  }
}

Replace /path/to/mcp-proxy with the actual path you found in step 3.

Restart Claude Desktop
Claude Desktop will automatically discover the available Stata tools, allowing you to run Stata commands and analyze data directly from your conversations.

OpenAI Codex

You can use this extension with OpenAI Codex through mcp-proxy:

Make sure the Stata MCP extension is installed in VS Code or Cursor and currently running before attempting to configure Codex

Install mcp-proxy:

# Using pip
pip install mcp-proxy

# Or using uv (faster)
uv install mcp-proxy

Configure Codex by editing the config file at ~/.codex/config.toml:

On macOS/Linux (~/.codex/config.toml):

# Stata MCP Server (SSE Transport)
[mcp_servers.stata-mcp]
command = "mcp-proxy"
args = ["http://localhost:4000/mcp"]

On Windows (%USERPROFILE%\.codex\config.toml):

# Stata MCP Server (SSE Transport)
[mcp_servers.stata-mcp]
command = "mcp-proxy"
args = ["http://localhost:4000/mcp"]

If the file already contains other MCP servers, just add the [mcp_servers.stata-mcp] section.
Restart Codex or VS Code/Cursor
Codex will automatically discover the available Stata tools, allowing you to run Stata commands and analyze data directly from your conversations.

Troubleshooting Codex Configuration

If Codex is not recognizing the Stata MCP server:

Verify the MCP server is running (Status bar should show "Stata")
Check that the configuration file exists at ~/.codex/config.toml with the correct content
Ensure mcp-proxy is installed: pip list | grep mcp-proxy or which mcp-proxy
Try restarting VS Code or Cursor
Check the extension output panel (View > Output > Stata MCP) for any errors
Ensure there are no port conflicts (default port is 4000)

Cline

Open your Cline MCP settings file:
- macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Add the Stata MCP server configuration:

{
  "mcpServers": {
    "stata-mcp": {
      "url": "http://localhost:4000/mcp",
      "transport": "sse"
    }
  }
}

If the file already contains other MCP servers, just add the "stata-mcp" entry to the existing "mcpServers" object.
Save the file and restart VS Code.

You can also configure Cline through VS Code settings:

"cline.mcpSettings": {
  "stata-mcp": {
    "url": "http://localhost:4000/mcp",
    "transport": "sse"
  }
}

Troubleshooting Cline Configuration

If Cline is not recognizing the Stata MCP server:

Verify the MCP server is running (Status bar should show "Stata")
Check that the configuration file exists with the correct content
Try restarting VS Code
Check the extension output panel (View > Output > Stata MCP) for any errors

Cursor

The extension automatically configures Cursor MCP integration. To verify it's working:

Open Cursor
Press Ctrl+Shift+P (or Cmd+Shift+P on Mac) to open the Command Palette
Type "Stata: Test MCP Server Connection" and press Enter
You should see a success message if the server is properly connected

Cursor Configuration File Paths

The location of Cursor MCP configuration files varies by operating system:

macOS:
- Primary location: ~/.cursor/mcp.json
- Alternative location: ~/Library/Application Support/Cursor/User/mcp.json
Windows:
- Primary location: %USERPROFILE%\.cursor\mcp.json
- Alternative location: %APPDATA%\Cursor\User\mcp.json
Linux:
- Primary location: ~/.cursor/mcp.json
- Alternative location: ~/.config/Cursor/User/mcp.json

Manual Cursor Configuration

If you need to manually configure Cursor MCP:

Create or edit the MCP configuration file:
- macOS/Linux: ~/.cursor/mcp.json
- Windows: %USERPROFILE%\.cursor\mcp.json

Add the Stata MCP server configuration:

{
  "mcpServers": {
    "stata-mcp": {
      "url": "http://localhost:4000/mcp",
      "transport": "sse"
    }
  }
}

If the file already contains other MCP servers, just add the "stata-mcp" entry to the existing "mcpServers" object.
Save the file and restart Cursor.

Troubleshooting Cursor Configuration

If Cursor is not recognizing the Stata MCP server:

Verify the MCP server is running
Check that the configuration file exists with the correct content
Try restarting Cursor
Ensure there are no port conflicts with other running applications

Python Environment Management

This extension uses uv, a fast Python package installer built in Rust, to manage Python dependencies. Key features:

Automatic Python setup and dependency management
Creates isolated environments that won't conflict with your system
Works across Windows, macOS, and Linux
10-100x faster than traditional pip installations

If you encounter any UV-related errors during installation:

Install UV manually:

# Windows (PowerShell as Administrator)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Follow the Troubleshooting steps to reinstall the extension

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

Repository Reference

Looking for internal architecture notes?

See docs/REPO_STRUCTURE.md for a quick map of directories and build artefacts.
See docs/incidents/README.md for an index of historical debugging write-ups (streaming, notifications, timeouts, etc.).
See tests/README.md for the current set of diagnostics and accompanying Stata fixtures.

Troubleshooting

If you encounter issues with the extension, follow these steps to perform a clean reinstallation:

Windows

Close all VS Code/Cursor windows
Open Task Manager (Ctrl+Shift+Esc):
- Go to the "Processes" tab
- Look for any running Python or uvicorn processes
- Select each one and click "End Task"
Remove the extension folder:
- Press Win+R, type %USERPROFILE%\.vscode\extensions and press Enter
- Delete the folder deepecon.stata-mcp-0.x.x (where x.x is the version number)
- For Cursor: The path is %USERPROFILE%\.cursor\extensions

Install UV manually (if needed):

# Open PowerShell as Administrator and run:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart your computer (recommended but optional)
Install the latest version of the extension from the marketplace

macOS/Linux

Close all VS Code/Cursor windows

Kill any running Python processes:

# Find Python processes
ps aux | grep python
# Kill them (replace <PID> with the process numbers you found)
kill -9 <PID>

Remove the extension folder:

# For VS Code:
rm -rf ~/.vscode/extensions/deepecon.stata-mcp-0.x.x
# For Cursor:
rm -rf ~/.cursor/extensions/deepecon.stata-mcp-0.x.x

Install UV manually (if needed):

# Using curl:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using wget:
wget -qO- https://astral.sh/uv/install.sh | sh

Restart your terminal or computer (recommended but optional)
Install the latest version of the extension from the marketplace

Additional Troubleshooting Tips

If you see errors about Python or UV not being found, make sure they are in your system's PATH:
- Windows: Type "Environment Variables" in the Start menu and add the installation paths
- macOS/Linux: Add the paths to your ~/.bashrc, ~/.zshrc, or equivalent
If you get permission errors:
- Windows: Run VS Code/Cursor as Administrator
- macOS/Linux: Check folder permissions with ls -la and fix with chmod if needed
If the extension still fails to initialize:
1. Open the Output panel (View -> Output)
2. Select "Stata-MCP" from the dropdown
3. Check the logs for specific error messages
4. If you see Python-related errors, try manually creating a Python 3.11 virtual environment:
```
# Windows
py -3.11 -m venv .venv

# macOS/Linux
python3.11 -m venv .venv
```
For persistent issues:
1. Check your system's Python installation: python --version or python3 --version
2. Verify UV installation: uv --version
3. Make sure you have Python 3.11 or later installed
4. Check if your antivirus software is blocking Python or UV executables
If you're having issues with a specific Stata edition:
1. Make sure the selected Stata edition (MP, SE, or BE) matches what's installed on your system
2. Try changing the stata-vscode.stataEdition setting to match your installed version
3. Restart the extension after changing settings

When opening an issue on GitHub, please provide:

The complete error message from the Output panel (View -> Output -> Stata-MCP)
Your operating system and version
VS Code/Cursor version
Python version (python --version)
UV version (uv --version)
Steps to reproduce the issue
Any relevant log files or screenshots
The content of your MCP configuration file if applicable

This detailed information will help us identify and fix the issue more quickly. You can open issues at: GitHub Issues

Star History

License

MIT

Credits

Created by Lu Han, Published by DeepEcon.ai

Stata MCP Extension for VS Code and Cursor

This extension provides Stata integration for Visual Studio Code and Cursor IDE using the Model Context Protocol (MCP).

The extension allows you to:

Run Stata commands directly from VS Code or Cursor
Execute selections or entire .do files
View Stata output in the editor in real-time
Get AI assistant integration through the MCP protocol
Experience enhanced AI coding with Cursor, Cline, Claude Code, or Codex
Choose your Stata edition (MP, SE, or BE)

Features

Run Stata Commands: Execute selections or entire .do files directly from your editor
Syntax Highlighting: Full syntax support for Stata .do, .ado, .mata, and .doh files
AI Assistant Integration: Contextual help and code suggestions via MCP
Cross-platform: Works on Windows, macOS, and Linux
Automatic Stata Detection: Automatically finds your Stata installation
Real-time Output: See Stata results instantly in your editor

Demo

Watch how this extension enhances your Stata workflow with Cursor (or VS Code) and AI assistance:

Stata MCP Extension Demo

🎬 Full Video Version | 📄 View Generated PDF Report

Looking for other Stata integrations?

Use Stata with Notepad++ and Sublime Text 3? See here

Use Stata via Jupyter? See here

Requirements

Stata 17 or higher installed on your machine
UV package manager (automatically installed or can be installed manually if needed)

Installation

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.

VS Code Installation

Option 1: From VS Code Marketplace

Install this extension directly from the VS Code Marketplace.

code --install-extension DeepEcon.stata-mcp

Or:

Open VS Code
Go to Extensions view (Ctrl+Shift+X)
Search for "Stata MCP"
Click "Install"

Option 2: From .vsix file

Download the extension package stata-mcp-0.3.5.vsix from the releases page.
Install using one of these methods:

code --install-extension path/to/stata-mcp-0.3.5.vsix

Or:

Open VS Code
Go to Extensions view (Ctrl+Shift+X)
Click on "..." menu in the top-right
Select "Install from VSIX..."
Navigate to and select the downloaded .vsix file

Cursor Installation

Download the extension package stata-mcp-0.3.5.vsix from the releases page.
Install using one of these methods:

cursor --install-extension path/to/stata-mcp-0.3.5.vsix

Or:

Open Cursor
Go to Extensions view
Click on the "..." menu
Select "Install from VSIX"
Navigate to and select the downloaded .vsix file

Usage

Running Stata Code

Open a Stata .do file
Run commands using:
- Run Selection: Select Stata code and press Ctrl+Shift+Enter (or Cmd+Shift+Enter on Mac), or click the first button (▶️) in the editor toolbar
- Run File: Press Ctrl+Shift+D (or Cmd+Shift+D on Mac) to run the entire .do file, or click the second button in the toolbar
- Interactive Mode: Select Stata code and click the 📊 button in the editor toolbar to run the selection in an interactive window, or click without selection to run the entire file
View output in the editor panel or interactive window

Data Viewer

Access the data viewer to inspect your Stata dataset:

Click the View Data button (fourth button, table icon) in the editor toolbar
View your current dataset in a table format
Filter data: Use Stata if conditions to view subsets of your data
- Example: price > 5000 & mpg < 30
- Type your condition in the filter box and click "Apply"
- Click "Clear" to remove the filter and view all data

Graph Display Options

Control how graphs are displayed:

Auto-display graphs: Graphs are automatically shown when generated (default: enabled)
- Disable in Extension Settings: stata-vscode.autoDisplayGraphs
Choose display method:
- VS Code webview (default): Graphs appear in a panel within VS Code
- External browser: Graphs open in your default web browser
- Change in Extension Settings: stata-vscode.graphDisplayMethod

Stata Edition Selection

Select your preferred Stata edition (MP, SE, or BE) in the Extension Settings

Detailed Configurations

Extension Settings

Customize the extension behavior through VS Code settings. Access these settings via:

VS Code/Cursor: File > Preferences > Settings (or Ctrl+, / Cmd+,)
Search for "Stata MCP" to find all extension settings

Core Settings

Setting	Description	Default
`stata-vscode.stataPath`	Path to Stata installation directory	Auto-detected
`stata-vscode.stataEdition`	Stata edition to use (MP, SE, BE)	`mp`
`stata-vscode.autoStartServer`	Automatically start MCP server when extension activates	`true`

Server Settings

Setting	Description	Default
`stata-vscode.mcpServerHost`	Host for MCP server	`localhost`
`stata-vscode.mcpServerPort`	Port for the MCP server	`4000`
`stata-vscode.forcePort`	Force the specified port even if it's already in use	`false`

Graph Settings

Setting	Description	Default
`stata-vscode.autoDisplayGraphs`	Automatically display graphs when generated by Stata commands	`true`
`stata-vscode.graphDisplayMethod`	Choose how to display graphs: `vscode` (webview panel) or `browser` (external browser)	`vscode`

Log File Settings

Setting	Description	Default
`stata-vscode.logFileLocation`	Location for Stata log files: `extension` (logs folder in extension directory), `workspace` (same directory as .do file), or `custom` (user-specified directory)	`extension`
`stata-vscode.customLogDirectory`	Custom directory for Stata log files (only used when logFileLocation is set to `custom`)	Empty

Advanced Settings

Setting	Description	Default
`stata-vscode.runFileTimeout`	Timeout in seconds for 'Run File' operations	`600` (10 minutes)
`stata-vscode.debugMode`	Show detailed debug information in output panel	`false`
`stata-vscode.clineConfigPath`	Custom path to Cline configuration file (optional)	Auto-detected

How to Change Settings

Open VS Code/Cursor settings (Ctrl+, or Cmd+,)
Search for "Stata MCP"
Modify the desired settings
Restart the extension or reload the window if prompted

Log File Management

The extension automatically creates log files when running Stata .do files. You can control where these log files are saved:

Log File Locations

Extension Directory (default): Log files are saved in a logs folder within the extension directory, keeping your workspace clean
Workspace Directory: Log files are saved in the same directory as your .do file (original behavior)
Custom Directory: Log files are saved to a directory you specify

Changing Log File Location

Open VS Code/Cursor settings (Ctrl+, or Cmd+,)
Search for "Stata MCP"
Find "Log File Location" (stata-vscode.logFileLocation) and select your preferred option:
- extension: Save to extension directory (default)
- workspace: Save to same directory as .do file
- custom: Save to a custom directory
If using "Custom Directory", also set "Custom Log Directory" (stata-vscode.customLogDirectory) path

Benefits of Each Option

Extension Directory: Keeps your project workspace clean and organized
Workspace Directory: Log files stay with your .do files for easy reference
Custom Directory: Centralize all logs in one location across projects

Claude Code

Claude Code is Anthropic's official AI coding assistant available in VS Code and Cursor. Follow these steps to configure the Stata MCP server:

Installation

Install the Stata MCP extension in VS Code or Cursor (see Installation section above)
Start the Stata MCP server: The server should start automatically when you open VS Code/Cursor with the extension installed. Verify it's running by checking the status bar (should show "Stata").

Configuration

Once the Stata MCP server is running, configure Claude Code to connect to it:

Open your terminal or command palette

Run the following command to add the Stata MCP server:

claude mcp add --transport sse stata-mcp http://localhost:4000/mcp --scope user

Restart VS Code or Cursor
Claude Code will now have access to Stata tools and can help you:
- Write and execute Stata commands
- Analyze your data
- Generate visualizations
- Debug Stata code
- Create statistical reports

Verifying the Connection

To verify Claude Code is properly connected to the Stata MCP server:

Open a Stata .do file or create a new one
Ask Claude Code to help with a Stata task (e.g., "Load the auto dataset and show summary statistics")
Claude Code should be able to execute Stata commands and show results

Troubleshooting

If Claude Code is not recognizing the Stata MCP server:

Verify the MCP server is running (Status bar should show "Stata")
Check that you ran the claude mcp add command with the correct URL
Try restarting VS Code or Cursor
Check the extension output panel (View > Output > Stata MCP) for any errors
Ensure there are no port conflicts (default port is 4000)

Claude Desktop

You can use this extension with Claude Desktop through mcp-proxy:

Make sure the Stata MCP extension is installed in VS Code or Cursor and currently running before attempting to configure Claude Desktop

Install mcp-proxy:

# Using pip
pip install mcp-proxy

# Or using uv (faster)
uv install mcp-proxy

Find the path to mcp-proxy:

# On Mac/Linux
which mcp-proxy

# On Windows (PowerShell)
(Get-Command mcp-proxy).Path

Configure Claude Desktop by editing the MCP config file:

On Windows (typically at %APPDATA%\Claude Desktop\claude_desktop_config.json):

{
  "mcpServers": {
    "stata-mcp": {
      "command": "mcp-proxy",
      "args": ["http://127.0.0.1:4000/mcp"]
    }
  }
}

On macOS (typically at ~/Library/Application Support/Claude Desktop/claude_desktop_config.json):

{
  "mcpServers": {
    "stata-mcp": {
      "command": "/path/to/mcp-proxy",
      "args": ["http://127.0.0.1:4000/mcp"]
    }
  }
}

Replace /path/to/mcp-proxy with the actual path you found in step 3.

Restart Claude Desktop
Claude Desktop will automatically discover the available Stata tools, allowing you to run Stata commands and analyze data directly from your conversations.

OpenAI Codex

You can use this extension with OpenAI Codex through mcp-proxy:

Make sure the Stata MCP extension is installed in VS Code or Cursor and currently running before attempting to configure Codex

Install mcp-proxy:

# Using pip
pip install mcp-proxy

# Or using uv (faster)
uv install mcp-proxy

Configure Codex by editing the config file at ~/.codex/config.toml:

On macOS/Linux (~/.codex/config.toml):

# Stata MCP Server (SSE Transport)
[mcp_servers.stata-mcp]
command = "mcp-proxy"
args = ["http://localhost:4000/mcp"]

On Windows (%USERPROFILE%\.codex\config.toml):

# Stata MCP Server (SSE Transport)
[mcp_servers.stata-mcp]
command = "mcp-proxy"
args = ["http://localhost:4000/mcp"]

If the file already contains other MCP servers, just add the [mcp_servers.stata-mcp] section.
Restart Codex or VS Code/Cursor
Codex will automatically discover the available Stata tools, allowing you to run Stata commands and analyze data directly from your conversations.

Troubleshooting Codex Configuration

If Codex is not recognizing the Stata MCP server:

Verify the MCP server is running (Status bar should show "Stata")
Check that the configuration file exists at ~/.codex/config.toml with the correct content
Ensure mcp-proxy is installed: pip list | grep mcp-proxy or which mcp-proxy
Try restarting VS Code or Cursor
Check the extension output panel (View > Output > Stata MCP) for any errors
Ensure there are no port conflicts (default port is 4000)

Cline

Open your Cline MCP settings file:
- macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Windows: %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
- Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

Add the Stata MCP server configuration:

{
  "mcpServers": {
    "stata-mcp": {
      "url": "http://localhost:4000/mcp",
      "transport": "sse"
    }
  }
}

If the file already contains other MCP servers, just add the "stata-mcp" entry to the existing "mcpServers" object.
Save the file and restart VS Code.

You can also configure Cline through VS Code settings:

"cline.mcpSettings": {
  "stata-mcp": {
    "url": "http://localhost:4000/mcp",
    "transport": "sse"
  }
}

Troubleshooting Cline Configuration

If Cline is not recognizing the Stata MCP server:

Verify the MCP server is running (Status bar should show "Stata")
Check that the configuration file exists with the correct content
Try restarting VS Code
Check the extension output panel (View > Output > Stata MCP) for any errors

Cursor

The extension automatically configures Cursor MCP integration. To verify it's working:

Open Cursor
Press Ctrl+Shift+P (or Cmd+Shift+P on Mac) to open the Command Palette
Type "Stata: Test MCP Server Connection" and press Enter
You should see a success message if the server is properly connected

Cursor Configuration File Paths

The location of Cursor MCP configuration files varies by operating system:

macOS:
- Primary location: ~/.cursor/mcp.json
- Alternative location: ~/Library/Application Support/Cursor/User/mcp.json
Windows:
- Primary location: %USERPROFILE%\.cursor\mcp.json
- Alternative location: %APPDATA%\Cursor\User\mcp.json
Linux:
- Primary location: ~/.cursor/mcp.json
- Alternative location: ~/.config/Cursor/User/mcp.json

Manual Cursor Configuration

If you need to manually configure Cursor MCP:

Create or edit the MCP configuration file:
- macOS/Linux: ~/.cursor/mcp.json
- Windows: %USERPROFILE%\.cursor\mcp.json

Add the Stata MCP server configuration:

{
  "mcpServers": {
    "stata-mcp": {
      "url": "http://localhost:4000/mcp",
      "transport": "sse"
    }
  }
}

If the file already contains other MCP servers, just add the "stata-mcp" entry to the existing "mcpServers" object.
Save the file and restart Cursor.

Troubleshooting Cursor Configuration

If Cursor is not recognizing the Stata MCP server:

Verify the MCP server is running
Check that the configuration file exists with the correct content
Try restarting Cursor
Ensure there are no port conflicts with other running applications

Python Environment Management

This extension uses uv, a fast Python package installer built in Rust, to manage Python dependencies. Key features:

Automatic Python setup and dependency management
Creates isolated environments that won't conflict with your system
Works across Windows, macOS, and Linux
10-100x faster than traditional pip installations

If you encounter any UV-related errors during installation:

Install UV manually:

# Windows (PowerShell as Administrator)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

Follow the Troubleshooting steps to reinstall the extension

Repository Reference

Looking for internal architecture notes?

See docs/REPO_STRUCTURE.md for a quick map of directories and build artefacts.
See docs/incidents/README.md for an index of historical debugging write-ups (streaming, notifications, timeouts, etc.).
See tests/README.md for the current set of diagnostics and accompanying Stata fixtures.

Troubleshooting

If you encounter issues with the extension, follow these steps to perform a clean reinstallation:

Windows

Close all VS Code/Cursor windows
Open Task Manager (Ctrl+Shift+Esc):
- Go to the "Processes" tab
- Look for any running Python or uvicorn processes
- Select each one and click "End Task"
Remove the extension folder:
- Press Win+R, type %USERPROFILE%\.vscode\extensions and press Enter
- Delete the folder deepecon.stata-mcp-0.x.x (where x.x is the version number)
- For Cursor: The path is %USERPROFILE%\.cursor\extensions

Install UV manually (if needed):

# Open PowerShell as Administrator and run:
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Restart your computer (recommended but optional)
Install the latest version of the extension from the marketplace

macOS/Linux

Close all VS Code/Cursor windows

Kill any running Python processes:

# Find Python processes
ps aux | grep python
# Kill them (replace <PID> with the process numbers you found)
kill -9 <PID>

Remove the extension folder:

# For VS Code:
rm -rf ~/.vscode/extensions/deepecon.stata-mcp-0.x.x
# For Cursor:
rm -rf ~/.cursor/extensions/deepecon.stata-mcp-0.x.x

Install UV manually (if needed):

# Using curl:
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or using wget:
wget -qO- https://astral.sh/uv/install.sh | sh

Restart your terminal or computer (recommended but optional)
Install the latest version of the extension from the marketplace

Additional Troubleshooting Tips

If you see errors about Python or UV not being found, make sure they are in your system's PATH:
- Windows: Type "Environment Variables" in the Start menu and add the installation paths
- macOS/Linux: Add the paths to your ~/.bashrc, ~/.zshrc, or equivalent
If you get permission errors:
- Windows: Run VS Code/Cursor as Administrator
- macOS/Linux: Check folder permissions with ls -la and fix with chmod if needed
If the extension still fails to initialize:
1. Open the Output panel (View -> Output)
2. Select "Stata-MCP" from the dropdown
3. Check the logs for specific error messages
4. If you see Python-related errors, try manually creating a Python 3.11 virtual environment:
```
# Windows
py -3.11 -m venv .venv

# macOS/Linux
python3.11 -m venv .venv
```
For persistent issues:
1. Check your system's Python installation: python --version or python3 --version
2. Verify UV installation: uv --version
3. Make sure you have Python 3.11 or later installed
4. Check if your antivirus software is blocking Python or UV executables
If you're having issues with a specific Stata edition:
1. Make sure the selected Stata edition (MP, SE, or BE) matches what's installed on your system
2. Try changing the stata-vscode.stataEdition setting to match your installed version
3. Restart the extension after changing settings

When opening an issue on GitHub, please provide:

The complete error message from the Output panel (View -> Output -> Stata-MCP)
Your operating system and version
VS Code/Cursor version
Python version (python --version)
UV version (uv --version)
Steps to reproduce the issue
Any relevant log files or screenshots
The content of your MCP configuration file if applicable

This detailed information will help us identify and fix the issue more quickly. You can open issues at: GitHub Issues

Stata MCP Server

README Documentation

Stata MCP Extension for VS Code and Cursor

Features

Demo

Requirements

Installation

VS Code Installation

Option 1: From VS Code Marketplace

Option 2: From .vsix file

Cursor Installation

Usage

Running Stata Code

Data Viewer

Graph Display Options

Stata Edition Selection

Detailed Configurations

Core Settings

Server Settings

Graph Settings

Log File Settings

Advanced Settings

How to Change Settings

Log File Locations

Changing Log File Location

Benefits of Each Option

Installation

Configuration

Verifying the Connection

Troubleshooting

Troubleshooting Codex Configuration

Troubleshooting Cline Configuration

Cursor Configuration File Paths

Manual Cursor Configuration

Troubleshooting Cursor Configuration

Python Environment Management

Repository Reference

Troubleshooting

Windows

macOS/Linux

Additional Troubleshooting Tips

Star History

License

Credits

Quick Install

Quick Actions

Key Features

Stata MCP Server

README Documentation

Stata MCP Extension for VS Code and Cursor

Features

Demo

Requirements

Installation

VS Code Installation

Option 1: From VS Code Marketplace

Option 2: From .vsix file

Cursor Installation

Usage

Running Stata Code

Data Viewer

Graph Display Options

Stata Edition Selection

Detailed Configurations

Core Settings

Server Settings

Graph Settings

Log File Settings

Advanced Settings

How to Change Settings

Log File Locations

Changing Log File Location

Benefits of Each Option

Installation

Configuration

Verifying the Connection

Troubleshooting

Troubleshooting Codex Configuration

Troubleshooting Cline Configuration

Cursor Configuration File Paths