---
title: "MCP resources"
description: "Gemini CLI MCP resources 的用途：让外部系统提供可读资源、上下文和工具元数据，并和普通工具调用区分。"
verifiedAt: "2026-05-09"
---

MCP 不只提供工具，也可以提供 resources。resources 更像“外部系统暴露出来的上下文材料”，工具更像“可以执行的动作”。

> [!NOTE]
> Resources 是 MCP 的低风险入口。能先用只读 resource 解释清楚外部系统状态，就不要一上来开放写工具。

Gemini CLI 有两个相关工具：`list_mcp_resources` 负责发现已连接 MCP server 暴露了哪些资源；`read_mcp_resource` 负责按 URI 读取某个资源内容。它们都是只读能力，不需要确认。

官方参数很简单：`list_mcp_resources` 可以用 `serverName` 过滤某个 server，`read_mcp_resource` 需要传入具体 `uri`。列表结果通常会整理成 URI 和描述；读取结果会按文本或二进制处理，二进制内容可能只返回类型占位。

## resources 适合什么

- 文档片段。
- 数据库 schema。
- 项目状态。
- 服务元信息。
- 只读上下文。

## 和工具的区别

| 类型 | 重点 |
| --- | --- |
| Resource | 读上下文 |
| Tool | 执行动作 |

Resources 的价值在于“先理解，再行动”。例如数据库 MCP server 可以先暴露 schema resource，让 Gemini CLI 读取表结构；只有当你确认理解正确后，再开放写查询或迁移工具。

| Resource 内容 | 推荐格式 | 价值 |
| --- | --- | --- |
| 数据库 schema | JSON / Markdown | 先理解表结构再写查询 |
| API 文档 | Markdown | 降低模型凭记忆猜参数 |
| 项目运行状态 | JSON | 让 agent 读真实状态 |
| Runbook | Markdown | 把运维步骤变成可读上下文 |
| 权限说明 | JSON / Markdown | 解释哪些工具可用、哪些禁用 |

## 使用流程

1. 用 `list_mcp_resources` 看有哪些 server 和 URI。
2. 选择一个 resource URI，用 `read_mcp_resource` 读取内容。
3. 让 Gemini CLI 基于 resource 解释外部系统状态。
4. 如果需要执行动作，再单独决定是否允许 MCP tool。

对于二进制资源，Gemini CLI 可能只返回数据类型占位，不一定能直接理解内容。高价值上下文最好提供 text 或结构化 JSON。

## 设计边界

Resource 应该回答“现在系统是什么状态”，Tool 才回答“要不要执行动作”。如果一个 MCP server 只暴露写工具，没有只读资源，agent 会更容易在理解不足时直接调用动作。

商业项目建议给每个高风险工具配一个只读 resource。例如部署工具旁边放 `status://deploy/current`，数据库写工具旁边放 `schema://db/main`，工单写工具旁边放 `docs://ticketing/workflow`。这样 agent 可以先读上下文，再提出动作计划。

## 使用建议

能用 resource 提供上下文时，不要一上来给写工具。先让 Gemini CLI 读懂外部系统，再决定是否需要执行能力。

团队 MCP 设计时，优先把风险低、复用高的资料做成 resources，例如 API schema、运行手册、当前环境元信息、只读报表。写操作工具要单独分层、单独授权。

## URI 设计建议

Resource URI 要稳定、可读、可枚举。不要把短期 token、用户私有路径或一次性查询参数塞进 URI。更好的设计是用清晰命名表达资源类型：

```text
schema://main-db/public
runbook://deploy/frontend
status://service/api-prod
docs://internal/auth-flow
```

URI 稳定后，教程和 custom command 才能可靠引用它。否则每次资源名变化，agent 需要重新发现，自动化也会变脆。

不要把资源 URI 设计成含 token、时间戳或本机绝对路径的字符串。凭据应该走 MCP server 的环境变量或认证层，资源 URI 只表达资源身份。这样教程、脚本和审计日志都更容易复核。

## 验收方式

连接 MCP 后，不要直接让 agent 执行工具。先列 resources，读取一个已知资源，确认返回内容、URI、server 名称和描述都正确。这样能先验证上下文链路，再验证动作链路。

## 接下来去哪

<Cards>
  <Card title="Extensions" description="需要把 MCP、commands、themes、skills 打包分发时，继续看 extensions。" href="/docs/gemini-cli/official/03-tools-mcp/38-extensions" />
  <Card title="MCP server" description="回看 server transport、OAuth、工具发现和凭据传递。" href="/docs/gemini-cli/official/03-tools-mcp/36-mcp-server" />
  <Card title="文件系统工具" description="对比内置只读文件工具和 MCP resources 的职责边界。" href="/docs/gemini-cli/official/03-tools-mcp/31-file-system-tool" />
</Cards>

## 官方来源

- [Google Developers Gemini CLI](https://developers.google.com/gemini-code-assist/docs/gemini-cli?hl=zh-cn)
- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
