> ## 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.