# 为 GitHub Copilot CLI 添加 MCP 服务器

通过连接模型上下文协议 （MCP） 服务器来扩展 Copilot功能，以提供其他工具和上下文。

模型上下文协议 (MCP) 是一个开放标准，用于定义应用程序与大型语言模型 (LLM) 共享上下文的方式。 可以将 MCP 服务器连接到 GitHub Copilot CLI 以提供 Copilot 对外部工具、数据源和服务的访问权限。 有关 MCP 的概述，请参阅“[关于模型上下文协议 (MCP)](/zh/copilot/concepts/context/mcp)”。

## 添加 MCP 服务器

> \[!NOTE]
> GitHub MCP 服务器内置在Copilot CLI一起，无需任何其他配置即可使用。 以下步骤用于添加其他 MCP 服务器。

如果组织或企业配置了注册表 URL 和允许列表策略，则这些设置将应用于 Copilot CLI。 配置的注册表 URL 将显示为发现源，只有允许列表策略允许的服务器才能运行。

可以通过以下方式添加 MCP 服务器：

* [使用 `/mcp add` 命令](#using-the-mcp-add-command)
* [使用`copilot mcp add`子命令](#using-the-copilot-mcp-add-subcommand)
* [编辑配置文件](#editing-the-configuration-file)
* [为每个存储库添加 MCP 服务器](#adding-per-repository-mcp-servers)
* [从注册表进行搜索和安装（实验性）](#searching-and-installing-from-the-registry)

有关特定 MCP 服务器的安装说明、可用工具和 URL，请参阅 [GitHub MCP 注册表](https://github.com/mcp)。

### 使用 `/mcp add` 命令

1. 在交互模式下，输入 `/mcp add`。 将显示配置窗体。 使用 <kbd>Tab</kbd> 在字段之间导航。

2. 在 **服务器名称**旁边，输入 MCP 服务器的唯一名称。 这是您用来指代服务器的名称。

3. 在 **“服务器类型”** 旁边，按相应的数字选择类型。 以下类型可用：

   * **本地** 或 **STDIO**：启动本地进程并通过标准输入/输出进行通信（`stdin`/`stdout`）。 这两个选项的工作方式相同。
     **STDIO** 是标准的 MCP 协议类型名称，因此，如果希望配置与 VS Code、 Copilot cloud agentMCP 客户端和其他 MCP 客户端兼容，请选择此选项。
   * **HTTP** 或 **SSE**：连接到远程 MCP 服务器。
     **HTTP** 使用可流式传输的 HTTP 传输。
     **SSE** 将旧 HTTP 与 Server-Sent 事件传输配合使用，该传输在 MCP 规范中已弃用，但仍支持向后兼容。 <!-- markdownlint-disable-line GHD046 -->

4. 其余字段取决于所选的服务器类型：

   * 如果选择 **“本地”** 或 **“STDIO**”：

     * 在 **Command** 旁边输入用于启动服务器的命令，包括任何参数。 例如，`npx @playwright/mcp@latest`。 这对应于 JSON 配置文件中的 `command` 属性和 `args` 属性。
     * 在 **环境变量**旁边，可以选择指定服务器所需的环境变量，例如 API 密钥或令牌，例如 JSON 键值对。 例如，`{"API_KEY": "YOUR-API-KEY"}`。 变量 `PATH` 会自动继承自您的环境。 必须在此处配置所有其他环境变量。

   * 如果选择 **HTTP** 或 **SSE**：

     * 在 **URL** 旁边，粘贴远程服务器 URL。 例如，`https://mcp.context7.com/mcp`。
     * 在 **HTTP 标头**旁边，可以选择将 HTTP 标头指定为 JSON。 例如，`{"CONTEXT7_API_KEY": "YOUR-API-KEY"}`。

5. 在 **“工具”** 旁边，指定服务器中的哪些工具应可用。 输入 `*` 以包括所有工具，或提供逗号分隔的工具名称列表（无需引号）。 默认值为 `*`。

6. 按 <kbd>Ctrl</kbd>+<kbd>S</kbd> 保存配置。 MCP 服务器会立即添加并可用，无需重启 CLI。

### 使用 `copilot mcp add` 子命令

可以使用子命令从终端 `copilot mcp add` 添加 MCP 服务器，而无需进入交互模式。 服务器已添加到位于 `~/.copilot/mcp-config.json` 的用户配置中。

对于本地（stdio）服务器，请在 `--` 后提供该命令：

```shell copy
copilot mcp add SERVER-NAME -- COMMAND [ARGS...]
```

对于远程（HTTP/SSE）服务器，请指定传输并提供 URL：

```shell copy
copilot mcp add --transport http SERVER-NAME URL
```

还可以传递其他选项：

* `--env KEY=VALUE`：设置服务器的环境变量。 对多个变量重复此操作。
* `--header "HEADER: VALUE"`：设置远程服务器的 HTTP 标头。 对多个标头重复此操作。
* `--transport TRANSPORT`：设置传输类型（`stdio`或`http``sse`）。 默认值为 `stdio`。
* `--tools TOOLS`：指定要启用的工具。 对所有工具使用 `*`（默认值），使用逗号分隔的列表，或者对不使用任何工具使用 `""`。
* `--timeout MS`：设置超时（以毫秒为单位）。

#### 示例

添加本地 stdio 服务器：

```shell copy
copilot mcp add context7 -- npx -y @upstash/context7-mcp
```

添加包含环境变量的本地服务器：

```shell copy
copilot mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_GITHUB_PAT -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server
```

添加远程 HTTP 服务器：

```shell copy
copilot mcp add --transport http notion \
  https://mcp.notion.com/mcp
```

添加具有授权标头的远程服务器：

```shell copy
copilot mcp add --transport http \
  --header "Authorization: Bearer YOUR-TOKEN" \
  stripe https://mcp.stripe.com
```

### 编辑配置文件

通过编辑 `~/.copilot/mcp-config.json` 处的配置文件，还可以添加 MCP 服务器。 如果要共享配置或一次性添加多个服务器，这非常有用。

以下示例显示了具有本地服务器和远程 HTTP 服务器的配置文件：

```json copy
{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "npx",
      "args": ["@playwright/mcp@latest"],
      "env": {},
      "tools": ["*"]
    },
    "context7": {
      "type": "http",
      "url": "https://mcp.context7.com/mcp",
      "headers": {
        "CONTEXT7_API_KEY": "YOUR-API-KEY"
      },
      "tools": ["*"]
    }
  }
}
```

有关 MCP 服务器配置的详细信息，请参阅 [为存储库配置 MCP 服务器](/zh/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers#writing-a-json-configuration-for-mcp-servers)。

### 为每个存储库添加 MCP 服务器

可以通过将 JSON 文件添加到存储库来为特定项目配置 MCP 服务器。 如果希望服务器仅在处理该项目时可用，或者希望通过将其提交到存储库来与协作者共享 MCP 设置，这非常有用。

Copilot CLI 在以下位置查找项目级配置：

| 路径                               | 建议用途                 |
| -------------------------------- | -------------------- |
| `.mcp.json` （在工作目录到存储库根目录的任何目录中） | 本地或按签出配置;通常放置在项目根目录下 |
| `.github/mcp.json`               | 提交到存储库的共享配置          |

在 Git 存储库中启动 Copilot CLI 时，CLI 会从当前工作目录一直走到存储库根目录，在此过程中加载 MCP 配置文件。 如果同时`.mcp.json``.github/mcp.json`存在于同一目录中，`.mcp.json`则优先。 当服务器名称冲突时，离工作目录更近的文件中的定义优先。 项目级定义也优先于 `~/.copilot/mcp-config.json` 中的定义。 有关相对信任的详细信息，请参阅 [GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference#mcp-server-trust-levels)。

项目级文件既可以使用 `mcpServers` 中所示的 `~/.copilot/mcp-config.json` 顶级对象，也可以使用裸顶层格式，其中每个键都是 MCP 服务器名称。 例如，此配置使用 `mcpServers` 对象：

```json copy
{
  "mcpServers": {
    "playwright": {
      "type": "local",
      "command": "npx",
      "args": ["@playwright/mcp@latest"]
    }
  }
}
```

同一个服务器还可以配置为使用最简顶层格式：

```json copy
{
  "playwright": {
    "type": "local",
    "command": "npx",
    "args": ["@playwright/mcp@latest"]
  }
}
```

> \[!NOTE]
> 只有在首次启动时确认文件夹信任后，才会加载Project级 MCP 服务器。 它们在不受信任的目录中会被静默跳过。 有关文件夹信任的详细信息，请参阅 [关于 GitHub Copilot CLI](/zh/copilot/concepts/agents/copilot-cli/about-copilot-cli#trusted-directories)。

在提示模式（`copilot -p`）中，如果当前目录已受信任，项目级 MCP 服务器会自动加载。 如果目录不受信任，默认情况下会跳过项目级 MCP 服务器。 若要无论如何加载它们，请将 `GITHUB_COPILOT_PROMPT_MODE_WORKSPACE_MCP` 环境变量设置为 `true`，因为提示模式无法显示交互式信任提示。 有关详细信息，请参阅“[GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference#environment-variables)”。

`.vscode/mcp.json` 的 VS Code 文件不被 Copilot CLI 读取。 它使用不受支持的顶级密钥 `servers`。 若要将现有 `.vscode/mcp.json` 项迁移到 CLI 接受的格式，请参阅 [GitHub Copilot CLI 命令参考](/zh/copilot/reference/copilot-cli-reference/cli-command-reference#migrating-from-vscodemcpjson)。

### 从注册表搜索和安装

> \[!NOTE]
> 该 `/mcp search` 命令目前是一项实验性功能。 若要使用它，请从Copilot CLI命令行选项开始`‑‑experimental`，或在会话期间输入`/experimental on`。

可以使用交互模式下的GitHub命令直接从 [](https://github.com/mcp)发现和安装 MCP 服务器。 这样，便可以浏览可用的服务器、查看其详细信息并安装它们，而无需手动填写配置表单。

如果你的组织已配置自定义 MCP 注册表 URL，`/mcp search` 将连接到该注册表，而非默认的 GitHub 注册表。

1. 在交互式模式下，输入 `/mcp search` 以按星号浏览热门服务器，或 `/mcp search QUERY` 搜索特定服务器。 例如：

   ```text
   /mcp search context7
   ```

2. 将显示匹配服务器的键盘导航列表。 使用箭头键浏览结果。

3. 选择服务器以打开其配置窗体。 表单已预先填入从注册表中读取的服务器配置。 填写任何必填字段，例如 API 密钥或令牌。

4. 按 <kbd>Ctrl</kbd>+<kbd>S</kbd> 进行保存。 服务器已添加到您的 `mcp-config.json` 中，并立即启动。

## 管理 MCP 服务器

您可以使用交互模式下的 `/mcp` 命令，或通过终端使用 `copilot mcp` 子命令来管理已配置的 MCP 服务器。

### 在交互模式下使用 `/mcp` 命令

* **列出配置的 MCP 服务器：** 使用命令 `/mcp show`。 这将显示所有配置的 MCP 服务器及其当前状态。

* **查看有关特定服务器的详细信息：** 使用命令 `/mcp show SERVER-NAME`。 这会显示指定服务器的状态及其提供的工具列表。

* **编辑服务器的配置：** 使用命令 `/mcp edit SERVER-NAME`。

* **删除服务器：** 使用命令 `/mcp delete SERVER-NAME`。

* **禁用服务器：** 使用命令 `/mcp disable SERVER-NAME`。 禁用的服务器持续保持配置状态，但在当前会话中不被 Copilot 使用。

* **启用以前禁用的服务器：** 使用命令 `/mcp enable SERVER-NAME`。

### 在终端中使用 `copilot mcp` 子命令

还可以从终端管理 MCP 服务器，而无需进入交互模式。

* **列出所有配置的服务器：**

  ```shell copy
  copilot mcp list
  ```

  列出来自所有配置源（用户、工作区和插件）的服务器。 为 JSON 输出添加 `--json`。

* **查看服务器详细信息：**

  ```shell copy
  copilot mcp get SERVER-NAME
  ```

  显示服务器的类型、状态和可用工具。 为 JSON 输出添加 `--json`。

* **删除服务器：**

  ```shell copy
  copilot mcp remove SERVER-NAME
  ```

  从用户配置中删除服务器。

## 使用 MCP 服务器

添加 MCP 服务器后， Copilot 可以在与提示相关时自动使用它提供的工具。 还可以在提示中直接引用 MCP 服务器和特定工具，以确保使用它们。

## 延伸阅读

* [关于模型上下文协议 (MCP)](/zh/copilot/concepts/context/mcp)
* [使用 MCP（模型上下文协议）服务器扩展 GitHub Copilot 对话助手](/zh/copilot/how-tos/provide-context/use-mcp-in-your-ide/extend-copilot-chat-with-mcp)
* [为存储库配置 MCP 服务器](/zh/copilot/how-tos/copilot-on-github/customize-copilot/configure-mcp-servers)