跳至主要內容

安裝指南

5 分鐘內完成設定並上手。本指南涵蓋 24 個 MCP 客戶端的設定，包括 Claude Code, Claude Desktop, Cursor, VS Code / GitHub Copilot、和 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/claude-code-plugin
/plugin install maguyva@maguyva

這會安裝到你的使用者帳號。若是團隊使用，可在兩個指令都加上 --scope project，把外掛提交到儲存庫的 .claude/settings.json 中，讓團隊成員自動取得。

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

export MAGUYVA_API_KEY=mgv_xxxx

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

手動設定（.mcp.json）——進階
.mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

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",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Claude Desktop 只支援透過 Settings 以 OAuth『connectors』的形式連接遠端伺服器，不支援在 claude_desktop_config.json 中以標頭驗證的方式設定，因此這裡使用 mcp-remote 橋接程序（需要 Node.js / npx）。

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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

Cursor MCP 文件 →

VS Code / GitHub Copilot

新增到你專案中的 .vscode/mcp.json（或使用者設定）：

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

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

VS Code / GitHub Copilot MCP 文件 →

Windsurf

macOS: ~/.codeium/windsurf/mcp_config.json
Windows: %UserProfile%\.codeium\windsurf\mcp_config.json
Linux: ~/.codeium/windsurf/mcp_config.json

新增到你的 Windsurf MCP 設定：

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

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

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"

[mcp_servers.maguyva.http_headers]
Authorization = "Bearer ${MAGUYVA_API_KEY}"

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

Codex MCP 文件 →

GitHub Copilot CLI

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

.copilot/mcp-config.json
{
  "servers": {
    "maguyva": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

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}"
      }
    }
  }
}

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

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": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

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

這個用戶端目前還不支援使用自訂驗證標頭連接遠端 MCP 伺服器，因此會透過 mcp-remote 橋接程序連接（需要 Node.js / npx）。Maguyva 完全在遠端執行——只有橋接程序會在本機執行。

Cline MCP 文件 →

Roo Code

macOS: ~/Library/Application Support/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json
Windows: %AppData%\Code\User\globalStorage\rooveterinaryinc.roo-cline\settings\mcp_settings.json
Linux: ~/.config/Code/User/globalStorage/rooveterinaryinc.roo-cline/settings/mcp_settings.json

新增到你的 Roo Code MCP 設定：

mcp_settings.json
{
  "mcpServers": {
    "maguyva": {
      "type": "streamable-http",
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${MAGUYVA_API_KEY}"
      },
      "alwaysAllow": [],
      "disabled": false
    }
  }
}

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

Roo Code MCP 文件 →

Goose

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

新增到你的 Goose 設定：

config.yaml
extensions:
  maguyva:
    name: maguyva
    cmd: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    enabled: true
    envs:
      MAGUYVA_API_KEY: mgv_xxxx
    type: stdio

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

這個用戶端目前還不支援使用自訂驗證標頭連接遠端 MCP 伺服器，因此會透過 mcp-remote 橋接程序連接（需要 Node.js / npx）。Maguyva 完全在遠端執行——只有橋接程序會在本機執行。

Goose MCP 文件 →

LM Studio

LM Studio 透過其 Agent 設定支援 MCP 伺服器。請在 Settings → Agent → MCP Servers 中，使用標準的 mcpServers JSON 格式新增一台 MCP 伺服器。LM Studio 透過 stdio 連接 MCP 伺服器。 查看文件 →

Continue

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

新增到你的 Continue 設定（~/.continue/config.json）：

config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

這個用戶端目前還不支援使用自訂驗證標頭連接遠端 MCP 伺服器，因此會透過 mcp-remote 橋接程序連接（需要 Node.js / npx）。Maguyva 完全在遠端執行——只有橋接程序會在本機執行。

Continue MCP 文件 →

Amazon Q Developer

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

新增到你的 Amazon Q MCP 設定：

mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

這個用戶端目前還不支援使用自訂驗證標頭連接遠端 MCP 伺服器，因此會透過 mcp-remote 橋接程序連接（需要 Node.js / npx）。Maguyva 完全在遠端執行——只有橋接程序會在本機執行。

Amazon Q Developer MCP 文件 →

PyCharm

新增到你專案根目錄的 .ai/mcp/mcp.json，或貼到 Settings > Tools > AI Assistant > MCP 裡：

.ai/mcp/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

這個用戶端目前還不支援使用自訂驗證標頭連接遠端 MCP 伺服器，因此會透過 mcp-remote 橋接程序連接（需要 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 ${MAGUYVA_API_KEY}"
      }
    }
  }
}

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

Zed MCP 文件 →

Trae

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

.trae/mcp.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

這個用戶端目前還不支援使用自訂驗證標頭連接遠端 MCP 伺服器，因此會透過 mcp-remote 橋接程序連接（需要 Node.js / npx）。Maguyva 完全在遠端執行——只有橋接程序會在本機執行。

Trae MCP 文件 →

OpenCode

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

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

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

OpenCode MCP 文件 →

BoltAI

macOS: ~/Library/Application Support/BoltAI/mcp_config.json

新增到你的 BoltAI MCP 設定：

mcp_config.json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

這個用戶端目前還不支援使用自訂驗證標頭連接遠端 MCP 伺服器，因此會透過 mcp-remote 橋接程序連接（需要 Node.js / npx）。Maguyva 完全在遠端執行——只有橋接程序會在本機執行。

BoltAI MCP 文件 →

LibreChat

新增到你的 LibreChat 設定：

librechat.yaml
mcpServers:
  maguyva:
    command: npx
    args:
      - -y
      - mcp-remote
      - https://maguyva.tools/mcp
      - --header
      - "Authorization: Bearer ${MAGUYVA_API_KEY}"
    env:
      MAGUYVA_API_KEY: mgv_xxxx

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

這個用戶端目前還不支援使用自訂驗證標頭連接遠端 MCP 伺服器，因此會透過 mcp-remote 橋接程序連接（需要 Node.js / npx）。Maguyva 完全在遠端執行——只有橋接程序會在本機執行。

LibreChat MCP 文件 →

Antigravity

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

新增到你的 Antigravity MCP 設定：

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

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

Antigravity MCP 文件 →

Claude Cowork

Claude Cowork 使用與其他 Anthropic 用戶端相同的 MCP 格式：

{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://maguyva.tools/mcp",
        "--header",
        "Authorization: Bearer ${MAGUYVA_API_KEY}"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}

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

Claude Cowork MCP 文件 →

ChatGPT

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

Warp

Warp 在 Agent Mode 中支援 MCP 伺服器。設定透過 Warp UI（Settings → Agent Mode → MCP Servers）管理，並透過 Warp Drive 同步。新增伺服器時，貼上標準的 mcpServers JSON 即可。 查看文件 →

Maguyva 使用標準 MCP。任何支援此協定的客戶端都能連接——即使上方沒有官方指南。已記載 24 個客戶端，並持續新增中。

驗證您的設定#

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

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

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

儲存庫格式#

指定儲存庫時：

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

提示：使用 repository_context(action="info", repository="...") 或 repository_context(action="info", repository="...") 檢查儲存庫解析結果。v3 伺服器為無狀態，故任何儲存庫覆寫僅對單次呼叫生效。

疑難排解#

API 金鑰問題#

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

找不到儲存庫#

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

MCP 連線問題#

  • 確認 npx 可在您的 PATH 中使用
  • 檢查您的 API 權杖是否有效且尚未過期
  • 測試與 https://maguyva.tools/mcp 的連線
  • 檢查您客戶端的 MCP 設定語法

後續步驟#