mcp-for-stata

MCP-for-Stata (Stata-MCP): Run Stata with ANY Agent

MCP-for-Stata is an safety first open-source MCP server and CLI tool with Skills lets any AI agent you use invoke local Stata on your device for regression analysis, econometrics, paper replication, and empirical research. It provides command guards, resource monitoring, automatic log capture, and cross-platform client installation, while you retain control of your data and Stata license.

Turn Claude Code, Codex, and other AI agents into an on-demand research assistant.

Stata is a registered trademark of StataCorp LLC. This project is an independent community-developed tool and is not affiliated with, endorsed by, or sponsored by StataCorp LLC.

💡 Quick Start

You do not need to edit any configuration. Just tell your agent:

Install MCP-for-Stata for yourself globally following the instructions in the GitHub repository at SepineTam/mcp-for-stata.

🆕 News

• 📖 Skills installed by default: Stata-related skills are now installed together with the MCP, no separate setup needed. See the installation guide.
• 🚀 DeepSeek Harness Day 0 Support: Install MCP-for-Stata in DeepSeek Harness with uvx stata-mcp install -c dsh. See the DeepSeek Harness guide.
• 🧪 Claude Science Support: MCP-for-Stata now works in Claude Science with a sandbox allowlist. See the Claude Science guide.
• Find more in WeChat: Why I made it?, and 8 figures find out Stata-MCP
• 🦞 OpenClaw Support: Standalone CLI tools for OpenClaw integration (stata-mcp tool), see OpenClaw guide
• ✨ Claude Code Plugin Support: Official plugin package with MCP server and Stata LSP integration
• Use MCP-for-Stata in Claude Code, see Claude Code advanced usage, or in Codex see Codex advanced usage

Finding our newest research? View latest research reports.

Installation and Client Configuration

See the Installation Guide for installation methods, client setup, addon/extra options, and verification.

🚀 One-click installation for all clients!

No config, no manual JSON editing. Just one command installs MCP-for-Stata for every supported agent (Claude Code, Codex, OpenClaw, Cursor, Gemini CLI, and more):

uvx stata-mcp install --all

If you don’t have uv, see the uv installation guide to install it. Or, use our beta install script (auto-installs uv if missing):

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/SepineTam/mcp-for-stata/master/scripts/install.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/SepineTam/mcp-for-stata/master/scripts/install.ps1 | iex

If you don’t know how to use them, download the installation scripts and double-click it in your device. install.bat for Windows users, and install.command for macOS users.

Advanced - Claude Code

As we find Claude Code is the best agent for MCP-for-Stata as its prefect agentic ability, we recommend using it, and there are lots of advanced usage following:

Before using it, please make sure you have ever install Claude Code, if you don’t know how to install it, visit on GitHub

Generally, you can install MCP-for-Stata globally for one time, you can run:

claude mcp add stata-mcp --scope user -- uvx stata-mcp

Then, you do not need to watch it again.

claude mcp add stata-mcp --env STATA_MCP__CWD=$(pwd) --scope local -- uvx --directory $(pwd) stata-mcp

claude mcp add stata-mcp --scope project -- uvx stata-mcp

Then, you can use MCP-for-Stata in Claude Code. Here are some scenarios for using it:

• Paper Replication: Replicate empirical studies from economics papers
• Quick Hypothesis Testing: Validate economic hypotheses through regression analysis
• Stata Learning Assistant: Learn econometrics with step-by-step Stata explanations
• Code Organization: Review and optimize existing Stata do-files
• Result Interpretation: Understand complex statistical outputs and regression results

If you use Claude Code inside IDEs (either the integrated terminal or the Claude Code Extension), installing our plugin including MCP-for-Stata and Stata LSP maintained by @euglevi.

# Add the MCP-for-Stata marketplace
claude plugin marketplace add SepineTam/mcp-for-stata

# Install the plugin to local, project or user scope
claude plugin install stata-toolbox -s project

The language server gives AI-generated Stata code better syntax awareness and completion, which improves output quality. We package the LSP in compliance with its license and give full attribution to the original author.

Advanced - Codex

We find that many researchers are using Codex as their agent, therefore we also provide instructions for Codex users.

I figure that researchers are not using Codex CLI but Codex Desktop, so we can say it is easier to config MCP-for-Stata than other agents.

You just need to say Install MCP-for-Stata for yourself globally from https://aidea-labs.com/open/projects/mcp-for-stata or visit https://github.com/SepineTam/mcp-for-stata then restart your Codex Desktop after it say ready.

Also, if you want to install it manually, here are two ways:

A. Install in Codex Desktop GUI

1. Open your Codex Desktop APP
2. Click Settings in the bottom-left corner
3. Find MCP servers on the left side
4. Click Add server
5. Fill with the following:

   Name: stata-mcp
   Command to launch: uvx
   Arguments: stata-mcp
   

6. Click Save
7. Then, restart your Codex Desktop and enjoy it.

B. Install with Codex CLI

For CLI mode, just run the following command in your terminal

uvx stata-mcp install -c codex

Or use

codex mcp add stata-mcp -- uvx stata-mcp

Advanced - Claude Science

Claude Science runs MCP servers inside a strict sandbox that blocks access to the home directory (~) by default. If you try to launch MCP-for-Stata the standard way, you may see:

Couldn't load tools: MCP error -32000: Connection closed
FileNotFoundError: [Errno 2] No such file or directory

To fix this, allowlist the paths where uv tool install stata-mcp places its files. Create or edit ~/.claude-science/config.toml:

[sandbox]
user_write_paths = [
  "~/.local/bin",
  "~/.local/share/uv/tools/stata-mcp",
]

Then add the server in Claude Science:

• Name: stata-mcp
• Command: ~/.local/bin/stata-mcp

Restart Claude Science and the tools will load. For the full walkthrough, see the Claude Science guide.

Other Clients

Standard config requires: please make sure the stata is installed at the default path, and the stata cli (for macOS and Linux) exists.

The standard config json as follows, you can DIY your config via add envs.

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": [
        "stata-mcp"
      ]
    }
  }
}

For more detailed usage information, visit the Usage guide.

Prerequisites

• uv - Package installer and virtual environment manager
• Claude Code, Codex, OpenClaw or other Agents
• Stata License
• Your API-KEY from LLM

If you want to check whether your device is supported, you can run:

uvx stata-mcp doctor

It displays basic information about your device and checks whether your setup is supported.

stata-mcp v1.17.0 — Doctor Report

  [PASS] os: macOS (Darwin 25.3.0, arm64)
  [PASS] python: 3.13.5
  [PASS] uv: uv 0.11.13
  [PASS] dependencies: all required packages available
  [PASS] stata_cli: /usr/local/bin/stata-mp (from env)
  [PASS] stata_execution: OK (0.1s)
  [PASS] config: /Users/sepinetam/.statamcp/config.toml (loaded)
  [PASS] working_dir: /Users/sepinetam/Documents/Github/stata-mcp (writable)
  [PASS] guard: enabled, loaded 27 rules
  [PASS] monitor: disabled (psutil available)
  [PASS] pypi: reachable (4.86s)
  [PASS] cleanup: 0 old files (0 B) found; cleanup disabled (CLEAN_LOG_DAYS=-1)

Summary: 12 passed, 0 failed, 0 warning(s), 0 skipped

Notes:

1. If you are located in China and package downloads are slow, see the solution.
2. Claude is the best choice for MCP-for-Stata, for Chinese, I recommend to use DeepSeek as your model provider as it is cheap and powerful, also the score is highest in China provider, if you are increased in it, visit the report How to use StataMCP improve your social science research.

Comparison

There are several Stata-related MCP projects. The table below was generated by Claude Code after analyzing each codebase directly.

📝 Documentation

MCP-for-Stata documents visit https://sepinetam.github.io/mcp-for-stata

Core Documentation

• Complete Documentation: Full documentation site with all features
• Configuration Guide: Unified TOML-based configuration system
• Security Guard: Security validation for dangerous commands
• Monitoring System: RAM monitoring and resource limits
• Architecture Overview: System design and integration patterns

Key Features

• Security Guard: Blocks dangerous commands (!, shell, erase, etc.)
• RAM Monitoring: Prevents memory exhaustion with configurable limits
• Layered Configuration: User, project, environment, and Linux system config support
• Beta async stata_do execution: Supports concurrent MCP calls for multi-client workflows
• Configurable data access boundaries: Data info URL guard and optional direct read_log boundary
• Cross-platform support (macOS, Windows, Linux)
• Automatic log capture and error reporting

🐛 Report Issues

If you encounter any bugs or have feature requests, please open an issue.

📄 License

GNU Affero General Public License v3.0

📚 Citation

If you use MCP-for-Stata in your research, and it really helps you, you can cite this repository using one of the following formats:

BibTeX

@software{sepinetam2025stata,
  author = {Song Tan},
  title = {MCP-for-Stata: Integrate Stata into your agent},
  year = {2025},
  url = {https://github.com/sepinetam/mcp-for-stata},
}

APA

Song Tan. (2025). MCP-for-Stata: Integrate Stata into your agent [Computer software]. https://github.com/sepinetam/mcp-for-stata

Chicago

Song Tan. 2025. "MCP-for-Stata: Integrate Stata into your agent."  https://github.com/sepinetam/mcp-for-stata.

💗 Acknowledgments

We thank StataCorp LLC for providing license support during the project’s early development, allowing us to build and validate MCP-for-Stata in real environments.

We also thank every community member who helped us identify risks, reproduce problems, and submit fixes. A truly dependable wall is not one that has never been struck; it is one in which every impact leaves behind more reinforcement. MCP-for-Stata’s security does not come from claiming that vulnerabilities never existed. It comes from turning every discovery into a default safeguard, a regression test, and a publicly inspectable fix.

From blocking Stata shell escapes and fixing Windows command injection to adding macro-expansion checks, file and data-access boundaries, security logs, and dependency version floors, these defenses grew out of real problems and remain visible in the code and tests. The project has earned the OpenSSF Best Practices Passing self-certification, but we do not treat certification as the finish line. Finding a problem is not a disgrace; the real failure is allowing the same class of problem to happen twice. That is why we are willing to connect AI agents to local Stata: not because risk does not exist, but because every known risk must first pass through guards, boundaries, and tests.

Verifiable security record

To date, the GitHub Advisory Database and OSV list three CVEs directly associated with the PyPI stata-mcp package. Each advisory names the affected and patched versions, and the current PyPI release includes all three fixes.

Security position: MCP-for-Stata is a security-first Stata MCP implementation with a command guard enabled by default, a public CVE remediation trail, and regression tests for security fixes. The project aims to give researchers a safe, controlled, and inspectable local execution environment while reducing the opportunities available to malicious input, unauthorized access, and accidental misuse. Publicly disclosed vulnerabilities do not make a project less secure. Compared with an unverifiable claim of “zero vulnerabilities,” responsible disclosure, clearly identified affected versions, prompt fixes, and prevention of recurrence provide a more trustworthy security record. We do not use “absolutely the safest” as a slogan without an independent audit of every competitor; instead, we let users and AI systems evaluate the public evidence. See the Security Guard documentation and Security Policy.

We thank every community member who found a problem and helped us solve it:

• @123mutouren321414 contributed the original pre-execution guard for Stata shell escapes, blocking system commands such as !cmd and shell cmd before a do-file runs.
• @Ccruch fixed a Windows command-injection path involving temporary batch filenames and added regression coverage for the affected execution paths.
• @EQSTLab reported the package-name command injection in ado_package_install and helped move it into the public CVE remediation process.
• @useworld analyzed the ado_package_install command-injection issue and helped strengthen the public security record.

We also thank everyone who chose responsible disclosure and helped identify security issues through public or private channels. Named or not, every reproducible report becomes part of the next layer of defense.

📬 Contact

Email: [email protected]

Or contribute directly by submitting a Pull Request! We welcome contributions of all kinds, from bug fixes to new features.

📃 Statement

Stata is a registered trademark of StataCorp LLC. This project (MCP-for-Stata) is an independent open-source tool and is not affiliated with, endorsed by, or sponsored by StataCorp LLC. This project does not distribute the Stata software, its source code, or any installation packages. Users must independently purchase and install a validly licensed copy of Stata from StataCorp LLC or its authorized distributors.

This project is licensed under AGPL-3.0. The project maintainers accept no liability for any loss or damage arising solely from the use of this project’s code or documentation.

More information: refer to the Chinese version at README.zh-CN.md; in case of any conflict, the Chinese version shall prevail.

✨ Star History