跳至主要內容

安裝指南

5 分鐘內完成設定並上手。本指南涵蓋 23 個 MCP 用戶端的設定，包括 Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot、和 Devin Desktop (Windsurf) 等。

先決條件：你需要來自 app.maguyva.ai 的 API 金鑰，以及一個已連接的 GitHub 儲存庫。

環境設定

#

首先，將 API 金鑰設為環境變數。當你的 MCP 用戶端提供此次請求的預設值，或該金鑰僅能存取單一儲存庫時，省略 repository；否則請明確傳入。

macOS/Linux (Bash/Zsh)

# 
# Add to your shell profile for persistence:
echo 'export MAGUYVA_API_KEY="mgv_xxxx"' >> ~/.zshrc  # or ~/.bashrc
source ~/.zshrc  # reload

Windows (PowerShell)

# 
# Make it persist in your profile:
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的實際 API 金鑰。

用戶端設定

#

在下方選擇你的 MCP 用戶端，以取得對應的設定說明。

相容性說明： Maguyva 使用標準 MCP。任何支援 MCP 的用戶端都能連接到同一台伺服器，即使我們還沒為它寫官方設定指南。

Claude Code

從 Claude Code 市集安裝 Maguyva 外掛：

新增 Maguyva 市集，然後安裝外掛（在 Claude Code 內執行以下每個指令）：

/plugin marketplace add maguyva/agent-plugins
/plugin install maguyva@maguyva

/plugin install 會開啟外掛的詳細資訊，你可以在那裡選擇安裝範圍：只有你（user）、在這個儲存庫工作的所有人（project），或只有你且僅限這個儲存庫（local）。這些工作階段內的指令不支援 --scope 旗標。

這個外掛是透過 MAGUYVA_API_KEY 環境變數進行驗證。請在你的 shell 中設定它：

export MAGUYVA_API_KEY=mgv_xxxx

建議使用每專案獨立的 direnv（.envrc）——金鑰是以儲存庫為範圍的，因此每個專案各自設定的值，才能對應到各專案的存取權限。如果一把金鑰就能涵蓋你所有的工作，用全域的 shell export 也可以。

若是團隊使用，也可以改在 Claude Code 之外，從儲存庫根目錄執行這兩個指令的 shell 形式：

claude plugin marketplace add maguyva/agent-plugins --scope project
claude plugin install maguyva@maguyva --scope project

project 範圍會把外掛記錄到儲存庫的 .claude/settings.json，由你提交。這樣會為團隊成員啟用外掛，但不會幫他們下載，因此每位成員都要執行一次安裝指令。

手動設定（.mcp.json）——進階
claude mcp add 
claude mcp add --transport http maguyva https://maguyva.tools/mcp --header 'Authorization: Bearer ${MAGUYVA_API_KEY}'
.mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Claude Code 帶來什麼 →

Claude Code MCP 文件 →

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %AppData%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

新增到你的 Claude Desktop 設定檔：

claude_desktop_config.json 
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

claude_desktop_config.json 只能啟動本機伺服器，所以這裡使用 @maguyva/mcp 橋接（需要 Node.js / npx）。Claude Desktop 也能把 Maguyva 當成自訂連接器（Customize → Connectors）並附上 authorization 請求標頭來連線，但請求標頭目前僅開放給部分組織測試。

Maguyva 能為 Claude Desktop 帶來什麼 →

Claude Desktop MCP 文件 →

Cursor

macOS: ~/.cursor/mcp.json
Windows: %UserProfile%\.cursor\mcp.json
Linux: ~/.cursor/mcp.json

新增到你專案根目錄的 .cursor/mcp.json：

.cursor/mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

這份設定會從 MAGUYVA_API_KEY 環境變數讀取金鑰。請在用戶端啟動時所在的環境中，將它設為你從 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Cursor 帶來什麼 →

Cursor MCP 文件 →

VS Code / GitHub Copilot

加入專案中的 .vscode/mcp.json，或加入你設定檔的 mcp.json（執行 MCP: Open User Configuration）：

.vscode/mcp.json 
{
  "servers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

這份設定會從 MAGUYVA_API_KEY 環境變數讀取金鑰。請在用戶端啟動時所在的環境中，將它設為你從 app.maguyva.ai 取得的 API 金鑰。

這是 VS Code 格式（servers 鍵）。VS Code 會從它啟動時的環境解析 MAGUYVA_API_KEY 參照。它的 Add Server 流程現在優先使用可攜式 .mcp.json（mcpServers 鍵），GitHub Copilot CLI 也會讀取該檔案；但該檔案不支援 VS Code 的輸入變數與環境檔。

Maguyva 能為 VS Code / GitHub Copilot 帶來什麼 →

VS Code / GitHub Copilot MCP 文件 →

Devin Desktop (Windsurf)

macOS: ~/.config/devin/mcp_config.json
Windows: %APPDATA%\devin\mcp_config.json
Linux: ~/.config/devin/mcp_config.json

Windsurf 現已更名為 Devin Desktop。加入它的 MCP 設定檔：

mcp_config.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}

這份設定會從 MAGUYVA_API_KEY 環境變數讀取金鑰。請在用戶端啟動時所在的環境中，將它設為你從 app.maguyva.ai 取得的 API 金鑰。

預設代理 Devin Local 從 3.6 版起讀取這個檔案；更早的版本把伺服器存放在主設定檔中，並會在啟動時移到這裡。新對話不會以它啟動的舊版 Cascade 代理也會讀取同一個檔案。Devin Desktop 會從它啟動時的環境解析 MAGUYVA_API_KEY 參照。

Maguyva 能為 Devin Desktop (Windsurf) 帶來什麼 →

Devin Desktop (Windsurf) MCP 文件 →

Codex

macOS: ~/.codex/config.toml
Windows: %UserProfile%\.codex\config.toml
Linux: ~/.codex/config.toml

新增到你的 Codex CLI 設定（~/.codex/config.toml）：

.codex/config.toml 
[mcp_servers.maguyva]
url = "https://maguyva.tools/mcp"
bearer_token_env_var = "MAGUYVA_API_KEY"

這份設定會從 MAGUYVA_API_KEY 環境變數讀取金鑰。請在用戶端啟動時所在的環境中，將它設為你從 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Codex 帶來什麼 →

Codex MCP 文件 →

GitHub Copilot CLI

新增到 ~/.copilot/mcp-config.json：

~/.copilot/mcp-config.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}
copilot mcp add 
copilot mcp add --transport http --header "Authorization: Bearer mgv_xxxx" maguyva https://maguyva.tools/mcp

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 GitHub Copilot CLI 帶來什麼 →

GitHub Copilot CLI MCP 文件 →

Gemini CLI

macOS: ~/.gemini/settings.json
Windows: %UserProfile%\.gemini\settings.json
Linux: ~/.gemini/settings.json

新增到你的 Gemini CLI 設定（~/.gemini/settings.json）：

settings.json 
{
  "mcpServers": {
    "maguyva": {
      "httpUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      }
    }
  }
}

這份設定會從 MAGUYVA_API_KEY 環境變數讀取金鑰。請在用戶端啟動時所在的環境中，將它設為你從 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Gemini CLI 帶來什麼 →

Gemini CLI MCP 文件 →

Cline

macOS: ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json

新增到你的 Cline MCP 設定：

cline_mcp_settings.json 
{
  "mcpServers": {
    "maguyva": {
      "type": "streamableHttp",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Cline 帶來什麼 →

Cline MCP 文件 →

Goose

macOS: ~/.config/goose/config.yaml
Windows: %APPDATA%\Block\goose\config\config.yaml
Linux: ~/.config/goose/config.yaml

新增到你的 Goose 設定：

config.yaml 
extensions:
  maguyva:
    name: maguyva
    type: streamable_http
    uri: https://maguyva.tools/mcp
    enabled: true
    headers:
      Authorization: Bearer mgv_xxxx
    timeout: 300

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Goose 帶來什麼 →

Goose MCP 文件 →

LM Studio

在 LM Studio 右側邊欄開啟 Program 分頁，選擇 Install → Edit mcp.json，然後加入：

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

LM Studio MCP 文件 →

Continue

在工作區存成 .continue/mcpServers/maguyva.yaml（或把 mcpServers 項目加到 ~/.continue/config.yaml），然後在 ~/.continue/.env 設定 MAGUYVA_API_KEY：

.continue/mcpServers/maguyva.yaml 
name: Maguyva
version: 0.0.1
schema: v1
mcpServers:
  - name: maguyva
    type: streamable-http
    url: https://maguyva.tools/mcp
    requestOptions:
      headers:
        Authorization: Bearer ${{ secrets.MAGUYVA_API_KEY }}

這份設定會從 MAGUYVA_API_KEY 環境變數讀取金鑰。請在用戶端啟動時所在的環境中，將它設為你從 app.maguyva.ai 取得的 API 金鑰。

Continue 只在代理模式使用 MCP 伺服器。它依序在 ~/.continue/.env、工作區的 .continue/.env 與 .env，最後在程序環境中尋找機密。

Maguyva 能為 Continue 帶來什麼 →

Continue MCP 文件 →

Kiro CLI (Amazon Q Developer CLI)

macOS: ~/.kiro/settings/mcp.json
Windows: %USERPROFILE%\.kiro\settings\mcp.json
Linux: ~/.kiro/settings/mcp.json

加入 Kiro CLI 的 MCP 設定（~/.kiro/settings/mcp.json，專案中則是 .kiro/settings/mcp.json）：

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Kiro CLI 取代了 Amazon Q Developer CLI。安裝時會一次性把 ~/.aws/amazonq/mcp.json 中的伺服器複製到 ~/.kiro/settings/mcp.json；專案的 .kiro/settings/mcp.json 優先於使用者層級的檔案。

Kiro CLI (Amazon Q Developer CLI) MCP 文件 →

PyCharm

貼到 Settings | Tools | AI Assistant | Model Context Protocol (MCP) → Add，作為 JSON 設定： 

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

此設定使用 @maguyva/mcp 橋接程序（需要 Node.js / npx）。本指南尚未驗證此用戶端的原生遠端連線設定；這並不表示此用戶端不支援原生遠端連線。Maguyva 完全在遠端執行——只有橋接程序在本機執行。

PyCharm MCP 文件 →

Zed

macOS: ~/.config/zed/settings.json
Windows: %AppData%\Zed\settings.json
Linux: ~/.config/zed/settings.json

新增到你的 Zed 設定（~/.config/zed/settings.json）：

settings.json 
{
  "context_servers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Zed 帶來什麼 →

Zed MCP 文件 →

Trae

在 Settings → MCP 開啟 Enable Project MCP，然後加入專案根目錄的 .trae/mcp.json：

.trae/mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Trae MCP 文件 →

OpenCode

新增到你專案根目錄的 opencode.json：

opencode.json 
{
  "mcp": {
    "maguyva": {
      "type": "remote",
      "url": "https://maguyva.tools/mcp",
      "enabled": true,
      "headers": {
        "Authorization": "Bearer {env:MAGUYVA_API_KEY}"
      }
    }
  }
}

這份設定會從 MAGUYVA_API_KEY 環境變數讀取金鑰。請在用戶端啟動時所在的環境中，將它設為你從 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 OpenCode 帶來什麼 →

OpenCode MCP 文件 →

BoltAI

macOS: ~/.boltai/mcp.json

新增到你的 BoltAI MCP 設定：

mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

此設定使用 @maguyva/mcp 橋接程序（需要 Node.js / npx）。本指南尚未驗證此用戶端的原生遠端連線設定；這並不表示此用戶端不支援原生遠端連線。Maguyva 完全在遠端執行——只有橋接程序在本機執行。

BoltAI MCP 文件 →

LibreChat

加入 librechat.yaml，並在 LibreChat 伺服器的環境中設定 MAGUYVA_API_KEY：

librechat.yaml 
mcpServers:
  maguyva:
    type: streamable-http
    url: https://maguyva.tools/mcp
    headers:
      Authorization: Bearer ${MAGUYVA_API_KEY}
    requiresOAuth: false

這份設定會從 MAGUYVA_API_KEY 環境變數讀取金鑰。請在用戶端啟動時所在的環境中，將它設為你從 app.maguyva.ai 取得的 API 金鑰。

LibreChat MCP 文件 →

Antigravity

macOS: ~/.gemini/config/mcp_config.json
Windows: %UserProfile%\.gemini\config\mcp_config.json
Linux: ~/.gemini/config/mcp_config.json

新增到你的 Antigravity MCP 設定：

mcp_config.json 
{
  "mcpServers": {
    "maguyva": {
      "serverUrl": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Antigravity 帶來什麼 →

Antigravity MCP 文件 →

Claude Cowork

Claude Cowork 不會載入 claude_desktop_config.json 裡的伺服器；它以自訂連接器的方式連到遠端伺服器。在 Customize → Connectors 新增一個 URL 為 https://maguyva.tools/mcp 的自訂連接器，選擇 No sign-in，再新增一個 authorization 請求標頭，值為 Bearer 加上你的 API 金鑰。請求標頭目前僅開放給部分組織測試；如果對話框裡沒有 Request headers 區段，Cowork 暫時還無法向 Maguyva 驗證。 查看文件 →

ChatGPT

ChatGPT 在 Business、Enterprise 與 Edu 方案中，透過 Settings → Apps → Create 支援遠端 MCP 伺服器。你需要一個遠端 HTTPS 端點——ChatGPT 不支援本機 stdio 伺服器。設定方式請參考 OpenAI 的 MCP 指南。 查看文件 →

Warp

加入 ~/.warp/.mcp.json（專案中則是 .warp/.mcp.json），或貼到 Settings → Agents → MCP servers → + Add：

~/.warp/.mcp.json 
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer mgv_xxxx"
      }
    }
  }
}

將 mgv_xxxx 替換為你在 app.maguyva.ai 取得的 API 金鑰。

Maguyva 能為 Warp 帶來什麼 →

Warp MCP 文件 →

Maguyva 使用標準 MCP。任何支援此協定的用戶端都能連接——即使上方沒有官方指南。目前已提供 23 個用戶端的設定文件，並持續新增中。

驗證你的設定

#

連接後，試著向你的代理提出幾個問題：

  • 「我連接了哪些儲存庫？」 — 驗證連線是否正常
  • 「這個程式碼庫是如何處理身份驗證的？」 — 測試語意搜尋
  • 「找出所有呼叫資料庫的函式」 — 測試依賴關係搜尋
  • 「UserService 類別依賴什麼？」 — 測試符號查找

你應該會看到來自已連接儲存庫、附帶檔案路徑與行號的結果。若沒有，請查看下方的 troubleshooting section。

儲存庫格式

#

指定儲存庫時：

  • 含分支: "owner/repo:branch" (e.g., "owner/repository:develop")
  • 預設分支: "owner/repo"

提示：使用 repository_context(action="info", repository="...") 檢查儲存庫解析。覆寫儲存庫設定只對目前呼叫生效。

疑難排解

#

API 金鑰問題

#
  • 確認你的金鑰以 mgv_ 開頭
  • 檢查金鑰是否已正確設定於你的環境中
  • 確認金鑰尚未過期

找不到儲存庫

#
  • 確認該儲存庫已在 app.maguyva.ai 中連接
  • 檢查 owner/repo 格式是否正確
  • 確認你有該儲存庫的存取權限

MCP 連線問題

#
  • 若用戶端使用 @maguyva/mcp 橋接程式，請確認 PATH 中可找到 npx
  • 檢查你的 API 權杖是否有效且尚未過期
  • 測試與 https://maguyva.tools/mcp 的連線
  • 檢查你用戶端的 MCP 設定語法

後續步驟

#

相關

延伸閱讀