> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hitheo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 安装 MCP

> 在 Cursor、Claude Code、Warp、Windsurf、VS Code 或任何其他兼容 MCP 的 IDE 中设置 @hitheo/mcp。

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

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

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

<Note>
  每种方式都要求在启动你的 IDE 的那个 shell 中设置好 `THEO_API_KEY` 环境变量。如果你还没有密钥，请[获取一个](https://api.hitheo.ai)，或运行 `theo login` 按提示完成设置。
</Note>

## 前置条件

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

  ```bash theme={null}
  npm install -g @hitheo/sdk
  ```

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

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

```bash theme={null}
cd your-project
theo init
```

它会：

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

示例输出：

```text theme={null}
[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 后需要重新运行配置时，可以使用这种方式：

```bash theme={null}
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-reference/mcp-install) CLI 参考文档。

## 方式三 —— 手写配置

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

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

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

<Tabs>
  <Tab title="Cursor">
    **路径**：`<project>/.cursor/mcp.json`

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

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

  <Tab title="Claude Code">
    **路径**：`<project>/.mcp.json`，或使用 CLI 辅助命令：

    ```bash theme={null}
    claude mcp add theo npx -y @hitheo/mcp
    ```

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

  <Tab title="Warp">
    **路径**：`<project>/.warp/mcp.json`

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

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

  <Tab title="Windsurf">
    **路径**：`~/.codeium/windsurf/mcp_config.json`（用户级配置，非项目级）。

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

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

  <Tab title="VS Code">
    **路径**：`<project>/.vscode/mcp.json`

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

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

  <Tab title="其他 IDE">
    任何遵循 MCP `command` / `args` / `env` 配置格式的 IDE（大多数都是如此）都可以使用同样的配置块。把它放到该 IDE 期望的 MCP 服务器配置位置，设置好 `THEO_API_KEY`，然后重启即可。

    如果你必须直接调用 `node` 而不是 `npx`，可以全局安装该包，并指向对应的可执行文件：

    ```bash theme={null}
    npm install -g @hitheo/mcp
    which theo-mcp   # 绝对路径；例如 /usr/local/bin/theo-mcp
    ```

    然后使用 `"command": "theo-mcp"`，并将 `args` 设为空数组。
  </Tab>
</Tabs>

## 验证安装

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

> "Use the Theo MCP server to run a status check."

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

## 各文件的写入内容

| 文件 | 用途 | 权威来源 |
| - | - | - |
| `theo.config.json` | 角色、技能、默认模式、内联工具 | [项目配置](/mcp/project-config) |
| `.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` 是幂等的 —— 重复运行时会将改动合并进现有文件，而不是直接覆盖它们。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.