安裝 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>`

方式三 —— 手寫配置

驗證安裝

各文件的寫入內容