跳转到内容

安装指南

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 导出也可以。

如果是团队使用，也可以在 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 配置语法

后续步骤

#

相关

延伸阅读