Stata MCP

Stata MCP Skill

Instructions

1. Ensure the stata MCP server is registered (see project README for config) and request it if not already active.
2. When the user asks for Stata work:
   • Use run_command for ad-hoc syntax (trace=True for call stacks, raw=True for plain output).
   • Use load_data before analyses that require datasets.
   • Use get_data, describe, codebook, or get_variable_list to inspect data.
   • Use run_do_file for provided .do scripts.
   • Use export_graph/export_graphs_all for visualization requests.
   • Use get_help when the user wants Stata documentation.
   • Use get_stored_results to return r()/e() scalars/macros after commands for validation.
   • Use read_log to tail or retrieve output from long-running commands.
   • Use get_ui_channel to obtain a localhost HTTP endpoint for high-volume data browsing.
3. Surface rc/stderr info back to the user, referencing r()/e() codes.
4. If Stata isn't auto-discovered, remind the user to set STATA_PATH (examples in README).

Tool quick reference

Command Execution

• run_command(code, echo=True, as_json=True, trace=False, raw=False, max_output_lines=None): Run Stata syntax.

  • code: The Stata command(s) to execute.
  • echo: Include the command itself in output (default: True).
  • as_json: Return JSON envelope with rc/stdout/stderr/error (default: True).
  • trace: Enable set trace on for deeper error diagnostics (default: False).
  • raw: Return plain stdout/error message instead of JSON (default: False).
  • max_output_lines: Truncate output to this many lines (default: None for no truncation).
  • Note: Always writes output to a temporary log file and emits a notifications/logMessage with {"event":"log_path","path":"..."} so the client can tail it locally.

• run_do_file(path, echo=True, as_json=True, trace=False, raw=False, max_output_lines=None): Execute .do files.

  • path: Path to the .do file.
  • echo: Include commands in output (default: True).
  • as_json: Return JSON envelope (default: True).
  • trace: Enable trace mode for debugging (default: False).
  • raw: Return plain output instead of JSON (default: False).
  • max_output_lines: Truncate output to this many lines (default: None).
  • Note: Always writes output to a temporary log file and emits incremental notifications/progress when the client provides a progress token/callback.

• read_log(path, offset=0, max_bytes=65536): Read a slice of a previously-provided log file.

  • path: Path to the log file (from notifications/logMessage).
  • offset: Byte offset to start reading from (default: 0).
  • max_bytes: Maximum bytes to read (default: 65536).
  • Returns JSON: path, offset, next_offset, data.

Data Loading & Inspection

• load_data(source, clear=True, as_json=True, raw=False, max_output_lines=None): Load data using sysuse/webuse/use heuristics.

  • source: Dataset name, URL, or file path (e.g., "auto", "webuse nlsw88", "/path/to/file.dta").
  • clear: Append , clear to replace existing data (default: True).
  • as_json: Return JSON envelope (default: True).
  • raw: Return plain output (default: False).
  • max_output_lines: Truncate output to this many lines (default: None).

• get_data(start=0, count=50): Retrieve a slice of the active dataset as JSON.

  • start: Zero-based index of first observation (default: 0).
  • count: Number of observations to retrieve (default: 50, max: 500).

• describe(): Return variable descriptions, storage types, and labels.

• get_variable_list(): Return JSON list of all variables with names, labels, and types.

• codebook(variable, as_json=True, trace=False, raw=False, max_output_lines=None): Return codebook/summary for a specific variable.

  • variable: Variable name to describe.
  • as_json: Return JSON envelope (default: True).
  • trace: Enable trace mode (default: False).
  • raw: Return plain output (default: False).
  • max_output_lines: Truncate output to this many lines (default: None).

Graph Management

• list_graphs(): List all graphs in Stata's memory with active graph marked.

• export_graph(graph_name=None, format="pdf"): Export a stored graph to file.

  • graph_name: Name of graph to export (from list_graphs); if None, exports active graph.
  • format: Output format—"pdf" (default) or "png". Use "png" to view plots directly.

• export_graphs_all(): Export all graphs in memory. Returns file paths by default.

Help & Results

• get_help(topic, plain_text=False): Return Stata help text.

  • topic: Command or help topic (e.g., "regress", "graph").
  • plain_text: Return plain text instead of Markdown (default: False).

• get_stored_results(): Return current r() and e() results as JSON after a command.

UI Data Browser

• get_ui_channel(): Return a short-lived localhost HTTP endpoint + bearer token for the UI-only data browser.
  • Returns JSON with baseUrl, token, expiresAt, and capabilities.
  • Intended for VS Code extension UI to browse data at high volume (paging, filtering, sorting) without sending large payloads over MCP.
  • Loopback only (binds to 127.0.0.1), requires bearer auth.

Cancellation

• Clients may cancel an in-flight request by sending the MCP notification notifications/cancelled with params.requestId set to the original tool call ID.
• Pass a _meta.progressToken when invoking the tool if you want progress updates (optional).
• Cancellation is best-effort and depends on Stata surfacing BreakError.

MCP Resources

The server exposes these resources for MCP clients:

• stata://data/summary → summarize
• stata://data/metadata → describe
• stata://graphs/list → graph list
• stata://variables/list → variable list
• stata://results/stored → stored r()/e() results

Graph review workflow

1. Call list_graphs() to see available plots and identify the active graph.
2. Use export_graphs_all() to fetch file paths for every graph; view them directly in the client.
3. For a single plot, call export_graph(graph_name="GraphName", format="png") to get a viewable file.
4. Compare the rendered PNGs to the user spec (titles, axes labels, legends, colors, filters); state whether the graph matches and what to change.

Examples

Run a regression

# Load sample data and run regression
load_data("auto")
run_command("regress price mpg")
get_stored_results()  # Retrieve coefficients and statistics

Export a histogram

# Create and export a graph
run_command("histogram price")
list_graphs()  # Confirm graph exists
export_graph(graph_name="Graph", format="png")  # Export for viewing

Debug a do-file

run_do_file("/path/to/analysis.do", trace=True)

Inspect data structure

load_data("nlsw88", clear=True)
describe()
get_variable_list()
codebook("wage")
get_data(start=0, count=10)

Read log output from long-running command

# After run_command emits a log_path notification
read_log("/tmp/stata_log_abc123.log", offset=0)
# Continue reading with next_offset for incremental output
read_log("/tmp/stata_log_abc123.log", offset=4096)