使用指南

希望未来不再有star war。 - 让科研从 reg monkeys 变成有价值的研究。

本指南介绍如何在不同环境和智能体中集成和使用 Stata-MCP。

前提条件

在使用 Stata-MCP 之前，请确保你有： - 已安装 Stata 17+ 并具有有效许可证 - uv 包管理器或 Python 3.11+ - 已安装或可通过 uvx 使用 Stata-MCP

验证你的设置：

uvx stata-mcp --usable

新功能

点击展开

🔒 安全守卫系统

Stata-MCP 现在包含自动安全验证以防止危险命令：

# 默认自动启用
# 阻止：!, shell, erase, rm, run, do, include 等

# 安全代码正常执行
result = stata_mcp.stata_do("""
    sysuse auto
    regress price mpg weight
""")

# 危险代码被阻止
result = stata_mcp.stata_do("""
    ! rm -rf /  # ❌ 被安全守卫阻止
""")
# Error: Security validation failed

配置：

# ~/.statamcp/config.toml
[SECURITY]
IS_GUARD = true  # 默认：true

环境变量：

export STATA_MCP__IS_GUARD=true

详情请参阅安全文档。

📊 RAM 监控系统

监控和控制 Stata 进程内存使用：

# 启用监控，设置 8GB 限制
export STATA_MCP__IS_MONITOR=true
export STATA_MCP__RAM_LIMIT=8192

# 如果 RAM 超过限制，进程将被自动终止
result = stata_mcp.stata_do(large_analysis_code)

配置：

[MONITOR]
IS_MONITOR = false   # 默认：false
MAX_RAM_MB = -1      # -1 = 无限制，正值 = 以 MB 为单位的限制

详情请参阅监控文档。

⚙️ 统一配置系统

通过 TOML 文件或环境变量配置所有设置：

优先级：环境变量 > 配置文件 > 默认值

# 使用环境变量快速设置
export STATA_MCP__CWD="/projects/my-analysis"
export STATA_MCP__IS_GUARD=true
export STATA_MCP__IS_MONITOR=true
export STATA_MCP__RAM_LIMIT=16384

或使用配置文件（~/.statamcp/config.toml）：

[DEBUG]
IS_DEBUG = false

[DEBUG.logging]
LOGGING_ON = true
LOGGING_CONSOLE_HANDLER_ON = false
LOGGING_FILE_HANDLER_ON = true

[SECURITY]
IS_GUARD = true

[PROJECT]
WORKING_DIR = ""

[MONITOR]
IS_MONITOR = false
MAX_RAM_MB = -1

详情请参阅配置文档。

在 Python 中使用

使用 OpenAI Agents SDK

Stata-MCP 可以使用 OpenAI Agents SDK 与 Python 智能体集成。

方法 1：直接 MCP 服务器集成

# !uv pip install openai-agents
from agents import Agent, Runner
from agents.mcp import MCPServerStdio, MCPServerStdioParams

# 创建 MCP 服务器连接
stata_mcp_server = MCPServerStdio(
    name="Stata-MCP",
    params=MCPServerStdioParams(
        command="uvx",
        args=["stata-mcp"]
    )
)

# 使用 MCP 服务器初始化智能体
agent = Agent(
    name="Research Assistant",
    instructions="You are a helpful economics research assistant.",
    mcp_servers=[stata_mcp_server]
)

# 运行分析
result = await Runner.run(
    agent,
    input="Run a regression: log(wage) ~ age, educ, exper with nlsw88 data and report coefficients."
)

print(f"Result: \n> {result.final_output}")

方法 2：预配置的 StataAgent

# !uv pip install stata-mcp
from agents import Runner
from stata_mcp.agent_as import StataAgent

# 使用预配置的 Stata 智能体
agent = StataAgent()
result = await Runner.run(
    agent,
    input="Help me run a regression -> log(wage) ~ age, educ, exper with `nlsw88` data and report me the coefficients."
)
print(f"Result: \n> {result.final_output}")

智能体作为工具

将 Stata-MCP 作为工具嵌入到更大的智能体工作流程中：

# !uv pip install openai-agents stata-mcp
from agents import Agent, Runner
from stata_mcp.agent_as import StataAgent

# 创建 Stata 智能体并转换为工具
stata_agent = StataAgent(max_turns=100)
stata_tool = stata_agent.as_tool

# 嵌入到更大的研究工作流程中
researcher = Agent(
    name="Scientific Researcher",
    instructions="You are a helpful scientist conducting empirical research.",
    tools=[stata_tool]
)

# 运行组合智能体
result = await Runner.run(
    researcher,
    input="Analyze the relationship between education and wages using standard datasets."
)

在编码智能体中使用

Stata-MCP 设计用于与现代 AI 编码智能体无缝集成。以下是流行平台的测试配置。

Claude 插件（推荐）

我们推荐使用官方插件以获得最佳体验。因此在 Claude Code 中使用 Stata-MCP 的最简单方式是通过官方插件，它同时提供 MCP 服务器和 LSP 集成：

# 添加市场注册表
claude plugin marketplace add sepinetam/stata-mcp

# 全局安装插件
claude plugin install stata-toolbox -s user

如果你想与合作伙伴一起工作，也可以这样安装：

# claude plugin marketplace add sepinetam/stata-mcp

claude plugin install stata-toolbox@stata-plugin-lib -s project

然后，你可以在 .claude/settings.json 中找到该插件

{
  "enabledPlugins": {
    "stata-toolbox@stata-plugin-lib": true
  }
}

插件功能： - ✅ 一键安装 - ✅ MCP 服务器 + LSP 一起配置 - ✅ 预配置的最优 Stata LSP 设置

完整的插件文档请参阅 Claude 插件指南。

Claude Code 的手动 MCP 配置

或者，手动配置 MCP 服务器：

Claude Code 是我们推荐的 AI 辅助实证研究解决方案。

全局安装

claude mcp add stata-mcp -- uvx stata-mcp

基于项目的配置

对于研究项目，使用项目范围配置：

cd ~/Documents/MyResearchProject
claude mcp add stata-mcp --env STATA_MCP_CWD=$(pwd) --scope project -- uvx --directory $(pwd) stata-mcp

指定版本

要使用特定版本：

claude mcp add stata-mcp --env STATA_MCP_CWD=$(pwd) --scope project -- uvx --directory $(pwd) stata-mcp==1.13.0

验证安装：

claude mcp list

基于项目配置的优势： - 每个研究项目隔离 Stata-MCP 环境 - 项目目录内自动路径管理 - 无全局配置冲突

Codex（VS Code 扩展）

对于使用 Codex 扩展的 VS Code 用户，编辑 ~/.codex/config.toml：

[mcp_servers.stata-mcp]
command = "uvx"
args = ["stata-mcp"]

Cline

对于 Cline 用户，编辑位于 ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/setting/cline_mcp_settings.json 的 MCP 配置文件：

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": [
        "stata-mcp"
      ]
    }
  }
}

Cursor

注意： Cursor 的文件系统访问受限。默认情况下 MCP 服务器可能无法访问 Documents 目录。如果遇到问题，请尝试此配置：

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": [
        "stata-mcp"
      ],
      "env": {
        "STATA_MCP_CWD": "/path/to/your/project"
      }
    }
  }
}

将 /path/to/your/project 替换为你的实际研究目录。

在 AI 客户端中使用

大多数 AI 客户端遵循标准的 MCP 服务器配置格式。以下是通用配置模式：

标准配置（Claude Desktop、Cherry Studio 等）

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": [
        "stata-mcp"
      ]
    }
  }
}

带自定义工作目录的配置

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": [
        "stata-mcp"
      ],
      "env": {
        "STATA_MCP_CWD": "/path/to/working/directory"
      }
    }
  }
}

带环境变量的配置

{
  "mcpServers": {
    "stata-mcp": {
      "command": "uvx",
      "args": [
        "stata-mcp"
      ],
      "env": {
        "STATA_MCP_CWD": "/path/to/working/directory",
        "STATA_MCP_MODEL": "gpt-4",
        "STATA_MCP_API_KEY": "your-api-key",
        "STATA_MCP_API_BASE_URL": "https://api.openai.com/v1"
      }
    }
  }
}

环境变量

Stata-MCP 支持多个环境变量进行自定义：

变量	描述	默认值
`STATA_MCP_CWD`	Stata 操作的当前工作目录	`./`
`STATA_MCP_MODEL`	智能体模式的 LLM 模型	`gpt-3.5-turbo`
`STATA_MCP_API_KEY`	LLM 提供商的 API 密钥	`OPENAI_API_KEY`
`STATA_MCP_API_BASE_URL`	API 请求的基础 URL	`https://api.openai.com/v1`
`STATA_MCP_CLIENT`	客户端类型标识符	-

终端 REPL 模式

对于交互式会话，使用内置 REPL 智能体：

# 使用当前目录启动
uvx stata-mcp agent run

# 使用自定义工作目录启动
uvx stata-mcp agent run ~/Documents/MyResearch

使用方法： - 用自然语言输入你的研究问题 - 智能体维护对话上下文 - 输入 /exit 或 bye 退出

高级用法

自定义智能体指令

创建带特定指令的自定义 StataAgent：

from stata_mcp.agent_as import StataAgent

agent = StataAgent(
    instructions="""
    You are a labor economics specialist.
    Focus on causal inference methods like DID, RDD, and IV.
    Always robustness checks and placebo tests.
    """,
    max_turns=50
)

会话管理

REPLAgent 支持基于 SQLite 的会话持久化：

from stata_mcp.agent_as import REPLAgent

agent = REPLAgent(
    work_dir="~/research",
    session_id="my_experiment_1"  # 可选的自定义会话 ID
)

会话存储在 <work_dir>/.stata_sessions.db 中用于对话历史。

故障排除

常见问题

"Stata not found" - 验证 Stata 安装：which stata（macOS/Linux）或检查 PATH - 使用 StataFinder 配置指南设置自定义路径

"Module not found" 错误 - 确保依赖已安装：uv pip install openai-agents stata-mcp - 检查 Python 版本：需要 3.11+

MCP 服务器无法连接 - 验证 uvx stata-mcp --usable 通过所有检查 - 检查客户端的 MCP 服务器日志 - 使用 stdio 传输（默认）测试

调试模式

启用详细日志：

export STATA_MCP__IS_DEBUG=true
uvx stata-mcp agent run

最佳实践

项目结构：使用项目范围的 MCP 配置以获得更好的隔离
版本固定：在生产环境中指定确切版本：stata-mcp==1.13.0
数据管理：保持原始数据不可变；使用 processing/ 目录
会话清理：定期归档或清理旧的 SQLite 会话数据库
API 密钥：使用环境变量，切勿硬编码凭证

其他资源

概述 - 架构和设计
工具文档 - 可用的 MCP 工具
智能体指南 - 智能体特定文档
GitHub 仓库 - 源代码和问题

贡献

发现错误或有功能请求？请提交 issue 或发送 pull request。