安装 MCP

安装 Theo 的 MCP 服务器有三种方式，按人工操作量从少到多排列：

theo init —— 推荐方式。自动检测你机器上安装的所有受支持 IDE，并一次性为每个 IDE 写入正确的配置。
theo mcp install --ide <name> —— 针对单个 IDE 进行配置。
手写 mcp.json —— 适用于特殊环境，或我们尚未内置检测支持的 IDE。

三种方式安装的都是同一个包（@hitheo/mcp），并通过 npx -y @hitheo/mcp 让每个 IDE 指向它。区别仅在于它们各自写入哪些配置文件。

每种方式都要求在启动你的 IDE 的那个 shell 中设置好 THEO_API_KEY 环境变量。如果你还没有密钥，请获取一个，或运行 theo login 按提示完成设置。

前置条件

Node.js 18+，且 npx 已加入 $PATH（任何 LTS 版本均可）。
一个 Theo API 密钥，形如 theo_sk_…，并以 THEO_API_KEY 的形式在你的 shell 中导出。
（可选） 全局安装 @hitheo/sdk 包，以获得 theo CLI：
npm install -g @hitheo/sdk

方式一 —— `theo init`（推荐）

theo init 一条命令即可完成整个项目的初始化：

cd your-project
theo init

它会：

创建 theo.config.json（项目级配置）。
检测已安装的 IDE（Cursor、Claude Code、Warp、Windsurf、VS Code）。
为每个检测到的 IDE 写入对应的 mcp.json。
生成 .theo/RULES.md，让你的 IDE 智能体知道这些工具的存在。

示例输出：

[theo] Initializing Theo in this project...
[theo]   ✓ Created theo.config.json
[theo] Detecting IDEs...
[theo]   Found: Cursor, Warp
[theo] Writing MCP configurations...
[theo]   ✓ Cursor: .cursor/mcp.json
[theo]   ✓ Warp: .warp/mcp.json
[theo] Generating agent context...
[theo]   ✓ Created .theo/RULES.md
[theo] ✅ Theo initialized!

命令执行完成后，请重启每个 IDE。

方式二 —— `theo mcp install --ide <name>`

当你只想为单个 IDE 设置 MCP、不想动其他 IDE，或者在新装了某个 IDE 后需要重新运行配置时，可以使用这种方式：

theo mcp install --ide cursor      # 单个 IDE
theo mcp install --ide all         # 所有受支持的 IDE
theo mcp install                   # 自动检测已安装的 IDE

支持的 --ide 取值：cursor、claude-code、warp、windsurf、vscode、all。完整的参数列表请参见 theo mcp install CLI 参考文档。

方式三 —— 手写配置

我们支持的每个 IDE 都会读取一个包含 mcpServers.<name> 条目的 JSON 文件，该配置块在所有 IDE 中都是一样的：

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

IDE 会把 ${env:THEO_API_KEY} 展开为启动它的那个 shell 中的值，因此你永远不需要把密钥提交进仓库。请把该配置块放到下方对应 IDE 的路径中。

路径：<project>/.cursor/mcp.json

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

重新打开项目后，Cursor 会读取该文件。Theo 的工具会出现在智能体的工具菜单中，名为 theo_complete、theo_image 等。

路径：<project>/.mcp.json，或使用 CLI 辅助命令：

claude mcp add theo npx -y @hitheo/mcp

两种方式都可以。CLI 辅助命令会写入同一个 .mcp.json，并在 Claude Code 的用户级存储中添加一条记录，因此配置会在不同项目间保留。

路径：<project>/.warp/mcp.json

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

下次打开该项目时，Warp 的智能体会列出 Theo 的工具。

路径：~/.codeium/windsurf/mcp_config.json（用户级配置，非项目级）。

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

重启 Windsurf —— 该配置只在启动时读取一次。

路径：<project>/.vscode/mcp.json

{
  "mcpServers": {
    "theo": {
      "command": "npx",
      "args": ["-y", "@hitheo/mcp"],
      "env": { "THEO_API_KEY": "${env:THEO_API_KEY}" }
    }
  }
}

需要一个启用了 MCP 支持的 VS Code 版本（Insiders 版或较新的正式版）。写入文件后请重新加载窗口。

任何遵循 MCP command / args / env 配置格式的 IDE（大多数都是如此）都可以使用同样的配置块。把它放到该 IDE 期望的 MCP 服务器配置位置，设置好 THEO_API_KEY，然后重启即可。如果你必须直接调用 node 而不是 npx，可以全局安装该包，并指向对应的可执行文件：

npm install -g @hitheo/mcp
which theo-mcp   # 绝对路径；例如 /usr/local/bin/theo-mcp

然后使用 "command": "theo-mcp"，并将 args 设为空数组。

验证安装

重启 IDE 后，向智能体提出一个只有 Theo 才能回答的问题，以确认工具已加载：

“Use the Theo MCP server to run a status check.”

如果智能体没有看到这些工具，请参阅故障排查。最常见的原因是忘记重启；第二常见的原因是 THEO_API_KEY 是在与启动 IDE 不同的 shell 中设置的。

各文件的写入内容

文件	用途	权威来源
`theo.config.json`	角色、技能、默认模式、内联工具	项目配置
`.theo/RULES.md`	面向智能体的 Theo 工具说明	自动生成；可放心编辑
`.cursor/mcp.json`	Cursor 的 MCP 配置	见上方标准 MCP 配置块
`.mcp.json`	Claude Code 的 MCP 配置	见上方标准 MCP 配置块
`.warp/mcp.json`	Warp 的 MCP 配置	见上方标准 MCP 配置块
`~/.codeium/windsurf/mcp_config.json`	Windsurf 用户级 MCP 配置	见上方标准 MCP 配置块
`.vscode/mcp.json`	VS Code 的 MCP 配置	见上方标准 MCP 配置块

theo init 是幂等的 —— 重复运行时会将改动合并进现有文件，而不是直接覆盖它们。

入门

快速开始

核心概念

故障排查

技能

指南

MCP 服务器

Playground

控制台

安全与合规

更新日志

前置条件

方式一 —— `theo init`（推荐）

方式二 —— `theo mcp install --ide <name>`

方式三 —— 手写配置

验证安装

各文件的写入内容

​前置条件

​方式一 —— theo init（推荐）

​方式二 —— theo mcp install --ide <name>

​方式三 —— 手写配置

​验证安装

​各文件的写入内容

前置条件

方式一 —— `theo init`（推荐）

方式二 —— `theo mcp install --ide <name>`

方式三 —— 手写配置

验证安装

各文件的写入内容