CLI Reference

MCP-for-Stata provides a command-line interface (CLI) for various operations including starting MCP servers, running agent mode, and installing to different AI clients.

Installation

Verify your installation:

stata-mcp --version

Run diagnostics to check system health:

stata-mcp doctor

Note: --usable has been deprecated since v1.14.3. It still works in current releases but stata-mcp doctor is the recommended replacement in v1.16+ and may be removed in a later major release.

Commands

Start MCP Server

Start the MCP server with different transport methods:

# Start with stdio transport (default)
stata-mcp

# Explicitly specify transport method
stata-mcp -t stdio
stata-mcp -t sse
stata-mcp -t http

Server Subcommand

Use the server subcommand to control which MCP tools are registered:

# All tools, stdio transport (same as bare command)
stata-mcp server

# Core tools only (stata_do, get_data_info, help)
stata-mcp server --core

# All tools with HTTP transport
stata-mcp server --all -t http

# Core tools with SSE transport
stata-mcp server --core -t sse

Tool Profiles: - --all - Register all available tools (default) - --core - Register only core tools: stata_do, get_data_info, help

Transport Options: - stdio - Standard input/output (default) - sse - Server-Sent Events - http - HTTP transport (automatically converted to streamable-http)

Agent Mode

Deprecated: Agent mode is marked with FutureWarning since v1.16.x and will be removed in a future release. New workflows should use MCP server mode (stata-mcp server or stata-mcp install).

Run MCP-for-Stata in interactive agent mode:

# Start agent in current directory
stata-mcp agent run

# Start agent in specific directory
stata-mcp agent run --work-dir /path/to/project

Doctor Diagnostics

Run health checks to diagnose potential issues:

# Run all checks
stata-mcp doctor

# Show detailed information for each check
stata-mcp doctor --verbose

# Output in JSON format
stata-mcp doctor --json

# Run only specific checks (repeatable)
stata-mcp doctor --check stata --check python

# Preview cleanup actions without deleting (cleanup checks only)
stata-mcp doctor --check cleanup --dry-run

Common check names include stata, python, and cleanup. The --dry-run flag is interpreted by cleanup-style checks and previews destructive operations instead of executing them; other checks ignore it.

Update

Update stata-mcp to the latest version:

# Auto-detect install method and update
stata-mcp update

# Check if a newer version is available
stata-mcp update --check

# Show detected method and available update without executing
stata-mcp update --dry-run

# Force specific update method
stata-mcp update --method pip       # pip install
stata-mcp update --method uv-tool   # uv tool upgrade
stata-mcp update --method homebrew  # brew upgrade

Update Methods: auto (default), pip, uv-tool, homebrew

Note for uv tool users on versions before 1.17.2: Due to a detection bug in earlier versions, stata-mcp update may incorrectly detect pip and fail. Run uv tool upgrade stata-mcp once manually to reach 1.17.2 or later, after which stata-mcp update will work correctly.

Local Tool Commands

Run API-backed Stata tools directly from the CLI:

# Install an ado package from SSC (default source)
stata-mcp tool ado-install reghdfe

# Run a do-file and only read the log when execution fails
stata-mcp tool do /path/to/analysis.do --read-log-when-error true

# Read Stata help through the one-shot API helper
stata-mcp tool help regress --enable-smcl true

# Inspect a supported dataset
stata-mcp tool data-info /path/to/data.dta

# Read a generated log file
stata-mcp tool read-log /path/to/output.log

Tool subcommands: - stata-mcp tool ado-install <package_name> [--source ssc|net|github] - stata-mcp tool do <dofile_path> [--read-log-when-error true|false] [--enable-smcl true|false] - stata-mcp tool help <command> [--read-log-when-error true|false] [--enable-smcl true|false] - stata-mcp tool data-info <data_path> [--vars-list var1 var2 ...] - stata-mcp tool read-log <log_path> [--output-format full|core|dict]

Note: --read-log-when-error replaces the older --is-read-log flag. Unlike the old flag (which unconditionally read the log), the new flag reads the log only when the underlying execution reports an error.

Config Management

Inspect and update local CLI configuration stored in ~/.statamcp/config.toml:

# Print the entire config file
stata-mcp config

# Show a single value (cli is shorthand for STATA.STATA_CLI)
stata-mcp config show cli
stata-mcp config show STATA.STATA_CLI
stata-mcp config show SECURITY.IS_GUARD

# Set STATA_CLI explicitly
stata-mcp config set cli /path/to/stata

# Auto-detect STATA_CLI via StataFinder and persist it
stata-mcp config set cli

# Edit an existing key by dot-notation
stata-mcp config edit STATA.STATA_CLI /path/to/stata
stata-mcp config edit SECURITY.IS_GUARD false

The set subcommand currently accepts only the cli key. The edit subcommand accepts any existing Section.Key in the config file and rejects keys that are not already defined.

Install to AI Clients

Install MCP-for-Stata to various AI coding assistants:

# Install to all supported clients (no -c, no --json-file)
stata-mcp install

# Install to a specific client
stata-mcp install -c claude-code
stata-mcp install -c cursor

# Install to all clients explicitly
stata-mcp install --all

# Install into a custom JSON config file
stata-mcp install --json-file /path/to/config.json

# Install into a nested key inside a custom JSON config file
stata-mcp install --json-file /path/to/config.json --json-index mcp.servers

Supported Clients:

Client ID	Target	Aliases
`claude`	Claude Desktop
`claude-code`	Claude Code	`cc`
`cursor`	Cursor Editor
`cline`	Cline (VS Code extension)
`codex`	Codex
`gemini`	Gemini CLI
`opencode`	OpenCode
`openclaw`	OpenClaw
`hermes`	Hermes	`hermes-agent`

Docker-based Installation (sandbox-install)

Install Docker-based MCP-for-Stata to AI clients. Requires Docker and a valid Stata license.

# Basic usage with default settings (StataNow 19.5 MP)
uvx stata-mcp sandbox-install -l /path/to/stata.lic

# Specify Stata version and edition
uvx stata-mcp sandbox-install \
  --version 19_5 \
  --edition mp \
  -l /path/to/stata.lic \
  -c claude

# With resource limits
uvx stata-mcp sandbox-install \
  -V 18 \
  -e se \
  -l /path/to/stata.lic \
  --cpus 2 \
  --memory 4g

Stata Versions: 19_5, 18_5, 18

Stata Editions: mp (Multi-processor), se (Standard), be (Basic)

Options

Server Options

Option	Description
`--core`	Register only core tools (stata_do, get_data_info, help)
`--all`	Register all tools (default)
`-t`, `--transport`	MCP transport method (stdio/sse/http)

Global Options

Option	Short	Description
`--version`	`-v`	Show version information
`--help`	`-h`	Show help message
`--usable`	`-u`	(Deprecated) Check system compatibility, use `stata-mcp doctor` instead
`--transport`	`-t`	MCP transport method (stdio/sse/http)

Agent Options

Option	Description
`--work-dir`	Working directory for agent (default: current directory)

Config Options

Command	Description
`stata-mcp config`	Print the raw `~/.statamcp/config.toml` content
`stata-mcp config show <dot_key>`	Show one value. `cli` is shorthand for `STATA.STATA_CLI`; otherwise use `Section.Key`
`stata-mcp config set cli [value]`	Set `STATA.STATA_CLI`. Auto-detect via StataFinder when value is omitted
`stata-mcp config edit <dot_key> <value>`	Edit an existing `Section.Key` entry

Install Options

Option	Short	Description
`--client`	`-c`	Target client. Omitting both `-c` and `--json-file` is equivalent to `--all`
`--all`	`-a`	Install to all supported clients
`--json-file`		Custom target client config file path
`--json-index`		Dot-separated nested key path (e.g. `mcp.servers`); only valid together with `--json-file`

Doctor Options

Option	Description
`--verbose`	Show detailed information for each check
`--json`	Output report in JSON format
`--check`	Run only specified check names (repeatable)
`--dry-run`	Preview cleanup actions without deleting files (cleanup-style checks only)

Update Options

Option	Description
`--method`	Force specific update method (auto/pip/uv-tool/homebrew)
`--dry-run`	Show detected method without updating
`--check`	Only check if a newer version is available

Sandbox-Install Options

Option	Short	Default	Description
`--version`	`-V`	`19_5`	Stata version (19_5, 18_5, 18)
`--edition`	`-e`	`mp`	Stata edition (mp, se, be)
`--tag`		`latest`	Docker image tag
`--license-file`	`-l`	(required)	Path to Stata license file
`--client`	`-c`	`claude`	Target client
`--work-dir`		`./`	Working directory
`--cpus`		(none)	CPU core limit
`--memory`		(none)	Memory limit (e.g., 4g)

Examples

Basic Usage

# Check if MCP-for-Stata can run on your system
stata-mcp doctor

# Start MCP server for Claude Desktop
stata-mcp

# Start with SSE transport
stata-mcp -t sse

Development Workflow

# 1. Run diagnostics
stata-mcp doctor

# 2. Install to Claude Code
stata-mcp install -c claude-code

# 3. Inspect a dataset before writing the analysis
stata-mcp tool data-info /path/to/data.dta

Using with uvx

If you prefer not to install MCP-for-Stata globally, you can use uvx:

# Check version
uvx stata-mcp --version

# Run diagnostics
uvx stata-mcp doctor

# Run a do-file directly
uvx stata-mcp tool do /path/to/analysis.do

# Start the MCP server
uvx stata-mcp server

# Install to a client
uvx stata-mcp install -c cursor

Self-contained Install Scripts

The project root ships a set of self-contained installer scripts for users who do not already have uv or pip available. They bootstrap a Python toolchain and bring up stata-mcp in one step.

Script	Target platform	Typical use
`install.sh`	Unix shells (Linux, macOS, WSL)	`bash install.sh`
`install.command`	macOS Finder	double-click to launch in Terminal
`install.ps1`	Windows PowerShell	`powershell -ExecutionPolicy Bypass -File install.ps1`
`install.bat`	Windows command line	double-click or run from `cmd.exe`

These scripts are intended for first-time bootstrap on machines without a Python package manager. On machines that already have uv or pip, the standard uv tool install stata-mcp / pip install stata-mcp flow is preferred.

Exit Codes

0 - Success
1 - Error (invalid client, system incompatibility, etc.)
2 - Command line argument error

Environment Variables

MCP-for-Stata behavior can be configured through environment variables. See Configuration for details.

Key environment variables:

STATA_MCP_CWD - Working directory for Stata operations
STATA_MCP_LOGGING_ON - Enable/disable logging
STATA_MCP__IS_GUARD - Enable security guard validation
STATA_MCP__IS_MONITOR - Enable RAM monitoring

See the Configuration document for the complete list.

Troubleshooting

"Stata not found" Error

Ensure Stata is installed and accessible:

stata-mcp doctor

This will run diagnostics and check if Stata can be found on your system.

Permission Errors

Some operations may require appropriate permissions: - Installing to Claude Desktop may need admin/user privileges - Working directories must be writable

Transport Issues

If you encounter issues with specific transport methods: - Default to stdio for most use cases - Use --transport stdio explicitly if auto-detection fails