CLI Reference

For installation methods and a step-by-step setup, start with the Installation Guide.

MCP-for-Stata provides a command-line interface (CLI) for various operations including starting MCP servers 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

Discover Stata installations

uvx stata-mcp discover

Lists installed Stata applications on macOS and Windows, one absolute path per line, sorted and deduplicated. For example, on macOS:

/Applications/Stata/StataMP.app
/Applications/StataNow/StataMP.app

Windows returns executable paths such as C:\Program Files\Stata18\StataMP-64.exe. Discovery reads the installed application list and also checks PATH and STATA_CLI (or stata_cli). On Windows, common installation directories are also checked when installation records lack a location. Unregistered custom installations outside these locations may not be found.

The command does not launch Stata, verify licenses, or change configuration. No matches produces no output and exit code 0. Unsupported operating systems produce only OS not supported on stderr and exit code 1; the Python discovery function raises OSNotSupported. This restriction applies only to discover.

Global Config Override

Most users should use ~/.statamcp/config.toml and optional ./.statamcp/config.toml project files. For developer debugging, the CLI also accepts a config override:

stata-mcp -c /path/to/debug-config.toml server
stata-mcp server --config /path/to/debug-config.toml

Note: -c/--config is not recommended for normal use. When provided, Stata-MCP reads only that file and ignores the user/project config stack. On Linux, /etc/statamcp/config.toml still has the highest priority and can override this debug config. The install and verify subcommands keep their existing -c/--client meaning; use --config there if a debug config path is needed.

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:

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

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

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

# Standard tools plus high-risk ado installation
stata-mcp server --unsafe

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

Tool Profiles: - --all - Register standard tools, excluding high-risk installation (default) - --core - Register only core tools: stata_do, get_data_info, help - --unsafe - Add the high-risk ado_package_install tool

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

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.

Verify Installation

Check whether stata-mcp is already installed in a target MCP client or config file. This subcommand is read-only and never modifies configuration files.

# Check a supported client
stata-mcp verify -c claude

# Check a custom JSON config file
stata-mcp verify -f ~/.cursor/mcp.json

# Check a nested config path
stata-mcp verify -f ~/.openclaw/openclaw.json --index mcp.servers

# Use a custom entry key
stata-mcp verify -f ~/.codex/config.toml --index mcp_servers --key stata-mcp

-c takes precedence over -f when both are provided.

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 approved ado package from SSC
stata-mcp tool ado-install reghdfe --yes

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

# Run with a custom log name and keep an existing log file
stata-mcp tool do /path/to/analysis.do --log-file-name quarterly_results --is-replace-log false

# Stop a do-file if execution exceeds five minutes
stata-mcp tool do /path/to/analysis.do --timeout 300

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

# 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> [-y|--yes] [--source ssc|net|github] - stata-mcp tool do <dofile_path> [--log-file-name <name>] [--is-read-log true|false] [--is-replace-log true|false] [--enable-smcl true|false] [--timeout <seconds>] - stata-mcp tool help <command> [--replace 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: --is-read-log true returns log content only when the underlying execution reports a Stata return-code error.

Without -y or --yes, ado-install asks for interactive confirmation. SSC and net package names may contain only ASCII letters and numbers. GitHub repositories require an exact repository allowlist and must be inspected before installation.

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

# Only install the base Stata MCP configuration
stata-mcp install -c codex --no-addon

# Include optional research tools from plugins/external
stata-mcp install -c codex --with-extra

# 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`
`workbuddy`	WorkBuddy	`wb`
`pi`	Pi coding agent	Explicit install only; requires `pi-mcp-adapter`
`copilot`	GitHub Copilot CLI	No aliases

Options

Server Options

Option	Description
`--core`	Register only core tools (stata_do, get_data_info, help)
`--all`	Register standard tools, excluding high-risk installation (default)
`--unsafe`	Add high-risk ado installation; requires explicit security configuration
`-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)
`--config`	`-c`	Debug-only `config.toml` path for developer use

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`
`--with-addon` / `--no-addon`		Install/skip supported components from GitHub `plugins/stata-toolbox` (default: on)
`--with-extra` / `--no-extra`		Install/skip supported components from GitHub `plugins/external` (default: off)
`--addon-ref REF`		Select a GitHub branch, tag or commit for both groups (default: `master`)

Addon and extra are independent: --no-addon --with-extra installs the base MCP plus external components. --all keeps these switches and processes each client once. An already configured Stata MCP does not prevent addon installation.

Payloads come from SepineTam/mcp-for-stata on GitHub, not from the wheel or the local checkout. Each invocation resolves the chosen ref to one immutable commit, fetches both selected directories from that commit, and records its SHA plus file SHA-256 hashes in ~/.statamcp/addons-v1.json. Re-running installation refreshes from GitHub; use --addon-ref <commit> to reproduce a particular snapshot. New external content must be pushed to the selected ref before it can be downloaded.

Base MCP and external MCP configuration share the same path resolver, including CODEX_HOME, CLAUDE_CONFIG_DIR and OpenCode's XDG_CONFIG_HOME overrides. Configuration tests do not establish that an installed client version can load every component. In particular, older Gemini releases may not expose skills; check gemini skills list in a version that supports Agent Skills. Unsupported components remain skipped rather than being reported as active.

Component support:

Client	Skill directory	Other components
Claude Code	`~/.claude/skills`	Rules, commands and agents in their corresponding user directories; LSP through a small managed native plugin
Codex	`~/.agents/skills`	External MCP entries in TOML
Gemini	`~/.gemini/skills`	External MCP entries in JSON
OpenCode	`~/.config/opencode/skills`	External MCP entries translated to local/remote format
Cursor	`~/.cursor/skills`	External MCP entries in JSON
Copilot CLI	`~/.copilot/skills`	External MCP entries in JSON
OpenClaw	`~/.openclaw/skills`	External MCP entries in JSON
Pi (explicit target only)	`~/.pi/agent/skills`	External stdio MCP entries; HTTP entries are skipped
Claude Desktop	Not installed	External stdio MCP entries; HTTP entries are skipped
Cline, WorkBuddy	Not installed	External MCP entries in JSON
Hermes, DSH	Not installed	Optional components currently skipped; base MCP still supported

Skills include their full directory (references, scripts and assets). Claude rules/commands/agents are namespaced under addon/ or extra/; instruction files such as CLAUDE.md are not edited. CLAUDE_CONFIG_DIR and XDG_CONFIG_HOME are respected for the corresponding skill directories. A custom JSON destination receives external MCP entries at --json-index; skills require a named client.

The Claude LSP adapter requires both claude and the declared language-server executable on PATH. It does not install the language-server executable. It uses a local, managed LSP-only plugin, preserving the base MCP configuration, and skips registration when an enabled native stata-toolbox already manages LSP. An explicitly disabled managed LSP plugin is left disabled. A native Stata toolbox does not suppress unrelated LSP definitions from the extra directory. Hooks and other unsupported component types are not automatically enabled. Downloaded scripts and external MCP commands are not run by the file installer; the client starts configured MCP servers when it loads them.

Existing files or config entries are upgraded only if the ownership manifest proves that they have not been modified locally. A conflicting file leaves the whole skill unchanged. Identical pre-existing files are skipped without claiming ownership. Upstream file removals require manual review instead of automatic deletion. Config backups live under ~/.statamcp/addon-backups/. Concurrent addon installs are refused while ~/.statamcp/addons.lock is held. If an install was interrupted, first verify that no installation process is running before removing that lock and retrying.

Downloads have time and size limits. Missing directories, network failures, conflicts and unsupported components produce visible warnings/skips without undoing the base MCP setup. Exit code 0 means base installation succeeded, not that every optional component was installed. Review the component messages; restart the client to load newly installed components. JSON settings may be reformatted; other entries are retained. Codex TOML updates preserve unrelated text and refuse unsupported layouts.

Directory conventions follow the official Claude memory, Codex skills, Gemini skills, OpenCode skills, Cursor skills, Copilot skills, OpenClaw skills, and Pi skills documentation. MCP serialization follows OpenCode's environment field, Cline's Streamable HTTP type, and OpenClaw's transport field.

Pi is excluded from --all because enabling MCP requires installing the third-party pi-mcp-adapter package. Run stata-mcp install -c pi explicitly. If Pi is not installed yet, the command prepares ~/.pi/agent/mcp.json and prints the remaining adapter installation command instead of claiming that the integration is active.

Developer verification:

# Offline configuration, parser, conflict and platform-path coverage
uv run pytest tests/cli tests/utils tests/test_install_scripts.py -q

# Optional native Codex/Claude configuration-read acceptance
STATA_MCP_NATIVE_INSTALL_TESTS=1 uv run pytest tests/utils/test_installer_native_clients.py -q

Native tests use disposable homes and inert commands for client health checks; they do not run Stata, call a model, or start the external research services. They test default/custom configuration directories and repeated installation. Missing CLIs are skipped. Simulated platform-path tests are not Windows/Linux application acceptance, and third-party service login/setup remains separate.

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)

Verify Options

Option	Short	Description
`--client`	`-c`	Target client key (e.g. `claude`, `cursor`, `codex`)
`--file`	`-f`	Path to a custom JSON or TOML config file
`--index`		Dot-separated nested key path, used with `-f` (e.g. `mcp.servers`)
`--key`		Entry key inside the target dict (default: `stata-mcp`)

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

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 scripts/ directory 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
`scripts/install.sh`	Unix shells (Linux, macOS, WSL)	`bash scripts/install.sh`
`scripts/install.command`	macOS Finder	double-click to launch in Terminal
`scripts/install.ps1`	Windows PowerShell	`powershell -ExecutionPolicy Bypass -File scripts/install.ps1`
`scripts/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 (system incompatibility, file not found, etc.)
2 - Command line argument error, or missing/invalid config key in verify
3 - Failed to parse JSON/TOML file in verify
4 - Invalid MCP server entry in verify (missing command or wrong type)
5 - verify subcommand argument error (missing -c/--client, invalid client, or missing -f/--file)

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