---
title: "MCP 和 Extensions"
description: "理解 Gemini CLI 如何通过 MCP 和 extensions 连接外部工具、数据源和团队工作流。"
verifiedAt: "2026-05-09"
---

MCP（Model Context Protocol，模型上下文协议）和 Extensions 解决的是同一个方向的问题：**让 Gemini CLI 不只看本地文件，而是能接入外部工具和能力**。

> [!NOTE]
> MCP 解决“连外部系统”，Extension 解决“打包本地能力”。不要因为两者都叫扩展，就把职责混在一起。

## MCP 是什么

MCP 可以理解为 AI agent 和外部系统之间的标准工具协议。一个 MCP server 可以暴露工具、资源或 prompt，让 Gemini CLI 调用。

典型场景：

- 查数据库。
- 读内部知识库。
- 调 GitHub、Slack、Notion、Linear。
- 调浏览器自动化。
- 接公司自研服务。

## Extensions 是什么

Extensions 更像 Gemini CLI 的能力包，可以带来配置、命令、工具、hooks 或文档。它适合把一组长期复用的能力打包分发。

可以这样区分：

```text
MCP          连接外部运行服务
Extension    打包 Gemini CLI 的本地能力和配置
Skill        让 agent 针对特定任务加载专门工作流
```

| 能力 | 主要解决 | 典型形态 |
| --- | --- | --- |
| MCP | 实时连接外部系统 | GitHub、数据库、浏览器、内部 API |
| Extension | 分发 Gemini CLI 配置和能力 | commands、hooks、MCP 配置、文档 |
| Skill | 让 agent 加载任务流程 | 审查、发布、迁移、资料整理 |

## 什么时候用 MCP

当任务需要实时访问外部系统时，用 MCP 更自然：

- 需要读 GitHub issue。
- 需要查询数据库。
- 需要调用浏览器。
- 需要访问内部 API。
- 需要把结果写回第三方平台。

如果只是固定规则或固定流程，先考虑 `GEMINI.md` 或 Skill，不要为了显得高级强行上 MCP。

## 安全边界

MCP server 的风险取决于它暴露什么能力：

- 只读资源风险低。
- 写入工具风险中。
- 能删数据、发消息、发布、付款的工具风险高。

生产环境里，MCP 工具应该有明确 allowlist、日志、权限隔离和人工确认策略。

## 接入前的三问

1. 这个 MCP server 暴露的是只读能力还是写入能力。
2. 凭据放在哪里，日志会不会打印 token 或内部数据。
3. 调用失败时，Gemini CLI 是重试、降级、还是交给人工处理。

如果这三问没有答案，就先不要把它接到真实项目。

## 最小接入思路

```text
先接只读 MCP -> 跑低风险查询 -> 确认返回格式 -> 加写入工具 -> 加审计和人工确认
```

不要第一天就把所有系统都接进去。

## 什么时候不用 MCP

这些情况通常先不用 MCP：

- 只是固定项目规则，用 `GEMINI.md`。
- 只是固定工作流，用 Skill 或 custom command。
- 只是本地命令，用 shell tool 或 script。
- 只是静态资料，用文档或资源文件。

MCP 应该服务于实时系统连接，不应该变成所有流程的万能入口。

## 上线前验收

MCP 接入前先验收只读 resource，再验收低风险 tool，最后才开放写操作。Extension 安装前先看 manifest、commands、MCP 配置、hooks 和脚本。两者都不能绕过凭据管理和日志审计。

如果只是教程内容，不需要实时系统，优先使用官方链接、静态文档和可复核来源，不要为了“更自动”额外接 MCP。

## 配置落地提示

MCP server 通常放在 `settings.json` 的 `mcpServers` 中，可能使用 command、url 或 httpUrl 这类 transport。凭据应该通过环境变量或系统凭据管理传入，不要写进教程或仓库。

Extension 则至少要看 `gemini-extension.json`、commands、context file、MCP 配置和 excludeTools。安装前先读这些文件，确认它没有偷偷扩大工具权限。

两者都要有禁用路径。不能关闭的外部能力，不适合放进团队默认配置。

## 资料型任务的替代方案

教程写作、官方资料核验、版本对比这类任务，不一定需要 MCP。用 Firecrawl 或官方网页抓取事实，再把来源写进文档，往往比接一个长期 MCP server 更简单、更可审计。

MCP 适合需要频繁读写外部系统的长期工作流，不适合一次性资料采集。

一次性官方资料采集还要保留抓取时间、来源 URL 和引用页面。这样后续内容过期时，只需要回到同一批来源复核，不必先排查某个长期 MCP server 是否还在线。

## 官方资料

- MCP servers：[docs/tools/mcp-server.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/tools/mcp-server.md)
- Extensions：[docs/extensions/index.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/extensions/index.md)
- MCP 协议规范：[modelcontextprotocol.io](https://modelcontextprotocol.io)
- Settings（mcpServers 配置）：[docs/cli/settings.md](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/settings.md)

## 下一篇

<Cards>
  <Card title="Skills、Subagents、Hooks" description="理解 MCP 之后，继续看能力包、分工和生命周期拦截。" href="/docs/gemini-cli/understanding/07-skills-subagents-hooks" />
  <Card title="MCP setup" description="需要实际配置 MCP server 时，回到官方 setup 页面。" href="/docs/gemini-cli/official/03-tools-mcp/35-mcp-setup" />
  <Card title="Extensions" description="需要打包和分发能力时，回到 Extensions 页面。" href="/docs/gemini-cli/official/03-tools-mcp/38-extensions" />
</Cards>
