Skip to content

SepineTam/mcp-for-stata / plugins/stata-toolbox/skills/stata-skill

stata-skill

Flagged

A packaged Stata Runner skill via official MCP-for-Stata server including stata_do, ado_package_install, help, read_log and get_data_info tools. Use it when (1) need to execute Stata do-file; (2) missing ado-packages; (3) find code error caused by syntax in Stata; (4) want to read smcl and text format log file with rich text output; (5) first encounter a data file and want to understand its structure and content.

MCP-for-Stata

Official plugin for MCP-for-Stata maintained in collaboration with SepineTam.

MCP-for-Stata (Stata-MCP) is an MCP (Model Context Protocol) server that exposes Stata's statistical and econometric capabilities to LLMs. This toolset supports executing do-files, querying data file structures, installing ado packages, reading Stata logs, and looking up command documentation.

Prerequisites

This skill requires the MCP-for-Stata server to be installed and running. If you have not configured it yet, follow @references/installation.md. After installation, verify with uvx stata-mcp doctor. Restart your AI client after installation (required for the first-time setup).

When to Use

Trigger this skill when the user mentions any of the following scenarios:

  • Needs to execute a Stata do-file for regression or statistical analysis
  • Encounters a Stata syntax error and needs to troubleshoot or verify command usage
  • Needs to install third-party ado packages (e.g., outreg2, reghdfe, estout)
  • First encounters a data file and wants to quickly understand its variable structure and distribution
  • Needs to read a Stata execution log (.log or .smcl)
  • Needs to look up the official documentation and syntax for a Stata command

Workflow

1. First Encounter with Data → get_data_info

When the user provides a data file path (.dta, .csv, .xlsx, .sav) or says "look at this data," call get_data_info first.

Key points:

  • data_path: absolute path to the data file
  • vars_list: if the user only cares about specific variables, pass a list of variable names; otherwise omit (defaults to all)
  • head: defaults to 0 (no preview rows). Only set to a positive integer when the user explicitly asks to see rows

Return value includes: data source, number of observations, variable list, variable types, and descriptive statistics (mean, standard error, min, max) for each variable.

Note: results are cached based on MD5 hash of file content. Repeated queries on the same file hit the cache.


2. Execute Stata Code → stata_do

When the user asks to run Stata commands, perform regression analysis, generate graphs, process data, etc., call stata_do.

Pre-requisites:

  1. Write Stata code into a .do file (using the Write tool)
  2. Confirm the file path is within an allowed directory (<WORKING_DIR>/.statamcp/stata-mcp-dofile/ or <WORKING_DIR>)
  3. Call stata_do(dofile_path=..., log_file_name=...)

Key parameters:

  • dofile_path: absolute path to the do-file
  • log_file_name: custom log filename without timestamp, optional
  • read_log_when_error: defaults to false. When true, only returns log content when Stata returns an error code (e.g., r(198))
  • enable_smcl: defaults to true, also generates .smcl log (Unix only)

Return value: log_file_path (text and smcl paths); may contain log_content on error.

Notes:

  • Security guard is enabled by default and blocks dangerous commands (shell, erase, rm, !, etc.)
  • Do-file must be within a whitelisted directory; otherwise execution is rejected
  • SMCL log preserves hyperlinks from commands like findsj and getiref (Unix only)

3. Install Third-Party Packages → ado_package_install

Treat ado_package_install as a high-risk, opt-in tool. Do not call it merely because a command is missing. First identify the exact package and source, then ask the user to approve that package and source. The MCP tool is available only when the operator starts the MCP server with the unsafe profile.

Key parameters:

  • package: package name. For GitHub source, use "user/repo" format
  • source: "ssc" (default), "github", or "net"
  • is_replace: defaults to false
  • package_source_from: required only when source="net", specifies a validated HTTPS URL

Authorization and validation: SSC and net package names may contain only ASCII letters and numbers. GitHub repositories must use owner/repository format and match the exact repository allowlist. Unknown sources, local paths, IP hosts, credentials, queries, fragments, and non-default ports are rejected. The MCP client will ask the user to approve the exact request during the tool call; do not attempt to bypass or pre-answer it. The Python API does not require caller confirmation. The CLI prompts unless -y or --yes is supplied.

Examples:

  • ado_package_install("outreg2") — request approval to install an SSC package
  • ado_package_install("SepineTam/TexIV", source="github") — request approval to install an allowlisted GitHub repository

Note: GitHub repository contents receive no security protection. Inspect the repository before installation. The tool never installs the GitHub helper. Successful installs automatically attempt help(..., replace=true) for the likely command name; if the package exposes other commands, refresh those commands explicitly.


4. Look Up Command Documentation → help

When the user asks about the syntax, options, or usage of a Stata command, or wants to verify a command before troubleshooting an error, call help.

Key parameter:

  • cmd: Stata command name (e.g., "regress", "describe", "xtset")
  • replace: defaults to false. When true, bypasses cached help and refreshes it from Stata

Return value: Stata help text string. A cache hit is prefixed with Saved result for {cmd} or Cached result for {cmd}.

Notes:

  • Unix only (macOS/Linux), not available on Windows
  • Enabled project and global caches are considered, and the newest non-empty result is returned
  • If cached content seems stale or incorrect, call help(cmd=..., replace=true) to refresh it

5. Read Execution Log → read_log

When the user asks to view a Stata execution log, analyze output results, or wants to inspect the full log after stata_do execution, call read_log.

Key parameters:

  • file_path: absolute path to the log file
  • output_format: "core" (default, removes framework lines), "dict" (structured command-result pairs), or "full" (all original content)
  • lines: content truncation. 0 returns all; positive returns first N items; negative returns last |N| items

Notes:

  • File must be within <WORKING_DIR>/<FOLDER_TAG>/ (security boundary)
  • Structured parsing is controlled by [BETA] enable_structured_log and is disabled by default

6. Export Tables and Figures → Output Defaults

When the user has NOT specified how an output should be produced, apply these presets — do not ask, do not invent alternatives. An explicit user request always overrides them.

OutputDefaultDetailed example
Regressionreghdfe with fixed effects in absorb() and vce(cluster <id>) at the treatment/assignment level; never regress when fixed effects are involved, never reflex , robust@examples/esttab-senior-guidance.md (setup section also covers reghdfe/ftools installation)
Regression tablesesttab (from estout), .tex with label booktabs fragment for papers, .rtf/.csv for quick sharing@examples/esttab-senior-guidance.md
Figuresgraph export name.png, width(2000) replace; PDF only for LaTeX papers@examples/graph-export-guidance.md

Package availability: reghdfe (+ ftools) and estout may not be installed. Check with help(cmd=...); if missing, use ado_package_install per section 3 — never ssc install inside a do-file. If installation is unavailable, tell the user exactly what to install manually.


Typical Workflow

Scenario A: Full Data Analysis Pipeline

  1. get_data_info — explore data structure
  2. Write do-file based on data characteristics (Write tool)
  3. Ask for approval and use ado_package_install; inspect GitHub repositories first
  4. stata_do — execute the do-file
  5. read_log — inspect execution results if needed

Scenario B: Troubleshooting Syntax Errors

  1. help — look up official command documentation (Unix only)
  2. Fix the code in the do-file
  3. stata_do — re-execute to verify

Scenario C: Install and Use a New Package

  1. Confirm the exact package and source with the user
  2. ado_package_install("pkgname") — request approval and install the package
  3. help(cmd="pkg_name", replace=true) — explicitly refresh and check package usage
  4. Use the package commands in the do-file
  5. stata_do — execute

Edge Cases

  • help Unix limitation: not available on Windows; guide users to alternative documentation methods
  • security guard enabled by default: dangerous commands (shell, erase, rm, !) in do-files are blocked. To disable, set STATA_MCP__IS_GUARD=false (not recommended)
  • RAM monitoring disabled by default: to monitor Stata process memory, set STATA_MCP__IS_MONITOR=true and STATA_MCP__RAM_LIMIT
  • path boundary check: do-files and log files must be within whitelisted directories; otherwise execution is rejected
  • SSC installation slow: ado_package_install from SSC source may take time; skip if the package is already installed

References

NameLocationDescription
Installation@references/installation.mdInstallation and configuration guide for MCP-for-Stata
stata_do@references/stata_do.mdDetailed guide for the execution tool
get_data_info@references/get_data_info.mdDetailed guide for the data exploration tool
help@references/help.mdDetailed guide for the documentation tool
read_log@references/read_log.mdDetailed guide for the log reader tool
ado_package_install@references/ado_package_install.mdDetailed guide for the package installer tool
esttab example@examples/esttab-senior-guidance.mdSenior-level example for exporting regression tables
graph export example@examples/graph-export-guidance.mdDefaults and pitfalls example for exporting figures
Documentationsepinetam.github.io/mcp-for-stataFull user documentation
HomepageMCP-for-Stata official websiteProject homepage
Source Codegithub.com/sepinetam/mcp-for-stataGitHub repository
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall