/stata-skill

name: stata-skill
description: |
  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.
metadata:
  version: "1.1.0"

MCP-for-Stata

> Official plugin for MCP-for-Stata maintained in collaboration with [SepineTam](https://github.com/sepinetam).

[MCP-for-Stata](https://aidea-labs.com/open/projects/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 onl