CLI Reference

Stata-MCP 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 is deprecated since v1.14.3 and will be removed in v1.16.0. Use stata-mcp doctor instead.

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

Run Stata-MCP 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

Local Tool Commands

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

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

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 print generated log output
stata-mcp tool do /path/to/analysis.do

# Read Stata help through the one-shot API helper
stata-mcp tool help regress --is-read-log true --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> [--is-read-log true|false] [--enable-smcl true|false] - stata-mcp tool help <command> [--is-read-log 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]

Config Management

Inspect and update local CLI configuration:

# Print current config file content (~/.statamcp/config.toml)
stata-mcp config

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

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

Install to AI Clients

Install Stata-MCP to various AI coding assistants:

# Install to Claude Desktop (default)
stata-mcp install

# Install to specific client
stata-mcp install -c claude    # Claude Desktop
stata-mcp install -c cc        # Claude Code
stata-mcp install -c gemini    # Gemini CLI
stata-mcp install -c cursor    # Cursor
stata-mcp install -c cline     # Cline
stata-mcp install -c codex     # Codex
stata-mcp install -c opencode  # OpenCode

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

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

Supported Clients: - claude - Claude Desktop - cc - Claude Code - gemini - Gemini CLI - cursor - Cursor Editor - cline - Cline (VSCode extension) - codex - Codex - opencode - OpenCode

Docker-based Installation (sandbox-install)

Install Docker-based Stata-MCP 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)
`--transport`	`-t`

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 raw config file content
`stata-mcp config cli set [value]`	Set `STATA.STATA_CLI` in config, auto-detect when value is omitted

Install Options

Option	Short	Description
`--client`	`-c`	Target client (default: claude)
`--all`	`-a`	Install to all supported clients
`--json-file`		Custom target client config file path

Doctor Options

Option	Description
`--verbose`	Show detailed information for each check
`--json`	Output report in JSON format
`--check`	Run only specified check names (repeatable)

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 Stata-MCP 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 Desktop
stata-mcp install

# 3. Run agent for interactive analysis
stata-mcp agent run

Using with uvx

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

# Check version
uvx stata-mcp --version

# Run diagnostics
uvx stata-mcp doctor

# Run agent
uvx stata-mcp agent run

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

Exit Codes

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

Environment Variables

Stata-MCP 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

CLI Reference

Installation

Commands

Start MCP Server

Server Subcommand

Agent Mode

Local Tool Commands

Doctor Diagnostics

Update

Local Tool Commands

Config Management

Install to AI Clients

Docker-based Installation (sandbox-install)

Options

Server Options

Global Options

Agent Options

Config Options

Install Options

Doctor Options

Update Options

Sandbox-Install Options

Examples

Basic Usage

Development Workflow

Using with uvx

Exit Codes

Environment Variables

Troubleshooting

"Stata not found" Error

Permission Errors

Transport Issues

See Also