Gemini CLI 中 MCP 服务器的完整配置与集成原理：settings.json 配置、发现机制、OAuth 认证与 gemini mcp 管理

Gemini CLI 中 MCP 服务器的完整配置与集成原理：settings.json 配置、发现机制、OAuth 认证与 gemini mcp 管理

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli

本文以 Gemini CLI 仓库中的官方文档 MCP servers with Gemini CLI 为主体，系统讲解如何在 Gemini CLI 中配置、认证、执行和运维 MCP（Model Context Protocol）服务器，并深入其核心包packages/core的发现（Discovery）与执行（Execution）实现，帮助读者既会写settings.json配置、使用gemini mcp命令管理服务器，又理解工具命名空间、环境脱敏与确认机制等底层设计。

什么是 MCP 服务器

MCP 服务器是一个通过 Model Context Protocol 向 Gemini CLI 暴露工具和资源（resources）的应用，充当 Gemini 模型与本地环境或外部服务（API、数据库等）之间的桥梁。它使 Gemini CLI 能够：

• 发现工具（Discover tools）：通过标准化 schema 定义列出可用工具、描述与参数；
• 执行工具（Execute tools）：以约定参数调用特定工具，并获取结构化响应；
• 访问资源（Access resources）：读取服务器暴露的特定资源（文件、API 载荷、报告等）。

借助 MCP 服务器，Gemini CLI 可以扩展出内置能力之外的操作，例如访问数据库、调用 API、执行自定义脚本或专用工作流。

核心集成架构

Gemini CLI 通过核心包中一套内建的发现与执行系统（位于 packages/core/src/tools/）与 MCP 服务器集成，分为发现层与执行层。

发现层（mcp-client.ts）

发现过程由 discoverMcpTools() 编排：

1. 遍历已配置的服务器：来自settings.json中的mcpServers配置；
2. 建立连接：根据配置选择 Stdio、SSE 或 Streamable HTTP 传输机制；
3. 拉取工具定义：通过 MCP 协议向每个服务器请求工具列表；
4. 清洗与校验：对工具 schema 进行消毒（sanitize），保证与 Gemini API 兼容；
5. 注册工具：将工具注册到全局工具注册表，并做冲突处理；
6. 拉取并注册资源：若服务器暴露了 resources 则一并注册。

从源码看，discoverMcpTools会对mcpServers的每一项并发调用 connectAndDiscover()（Promise.all驱动），单个服务器失败不会阻断其他服务器的发现；发现开始前状态置为IN_PROGRESS，结束（无论成败）后置为COMPLETED。

执行细节上，connectAndDiscover会同时发现prompts和tools：若两者皆为空则视为发现失败，主动关闭连接并把状态置为DISCONNECTED；只有真正注册到了内容，服务器状态才会被置为CONNECTED。此外源码中还有一个值得注意的健壮性设计——LenientJsonSchemaValidator：某些第三方服务器返回含$defs/$ref链的复杂 schema 时可能让 AJV 解析器抛错，该包装器在校验器编译失败时退化为 no-op 校验（同时输出 debug 日志），保证工具仍可被列出和使用。

执行层（mcp-tool.ts）

每个被发现的 MCP 工具都被包装为DiscoveredMCPTool实例（见 DiscoveredMCPTool）：

• 处理确认逻辑：基于服务器信任设置（trust）与用户选择；
• 管理工具执行：以正确参数调用 MCP 服务器；
• 处理响应：分别面向 LLM 上下文与用户展示生成不同格式；
• 维护连接状态并处理超时。

传输机制

Gemini CLI 支持三种 MCP 传输类型：

• Stdio Transport：派生子进程，通过 stdin/stdout 通信；
• SSE Transport：连接 Server-Sent Events 端点；
• Streamable HTTP Transport：使用 HTTP 流式通信。

使用 MCP 资源

部分 MCP 服务器除了工具和提示（prompts）外还会暴露上下文“资源”。Gemini CLI 会自动发现它们，并允许你在对话中引用。交互资源的内置工具详见 MCP resource tools。

发现与列出

• 发现运行期间，CLI 会拉取每个服务器的resources/list结果；
• /mcp命令会为每个已连接服务器在 Tools 和 Prompts 之外额外展示一个Resources区段，返回一份简洁的纯文本 URI 加元数据列表。

在对话中引用资源

你可以使用与引用本地文件相同的@语法：

@server://resource/path

资源 URI 会出现在补全菜单中（与文件系统路径并列）。提交消息后，CLI 调用resources/read并把内容注入对话上下文。

如何配置 MCP 服务器

Gemini CLI 使用settings.json中的mcpServers配置来定位并连接 MCP 服务器，支持以不同传输机制配置多个服务器。配置分为两部分：顶层mcpServers对象描述具体服务器，mcp对象控制发现与执行的全局行为。

全局 MCP 设置（mcp）

mcp对象为所有 MCP 服务器定义全局规则：

• mcp.serverCommand（string）：启动一个 MCP 服务器的全局命令；
• mcp.allowed（string 数组）：允许连接的服务器名白名单。设置后，只有与mcpServers键匹配的列表内服务器才会被连接；
• mcp.excluded（string 数组）：排除连接的服务器名黑名单。

{ "mcp": { "allowed": ["my-trusted-server"], "excluded": ["experimental-server"] } }

其中mcp.serverCommand在源码中的落地方式是 populateMcpServerCommand()：把命令字符串按 shell 语法解析后，以通用名mcp注入到mcpServers中，从而无需在对象里显式声明。

服务器级配置（mcpServers）

mcpServers对象中，每个键是一个服务器实例。典型结构如下：

{ "mcpServers": { "serverName": { "command": "path/to/server", "args": ["--arg1", "value1"], "env": { "API_KEY": "$MY_API_TOKEN" }, "cwd": "./server-directory", "timeout": 30000, "trust": false } } }

配置属性说明

每个服务器配置支持以下属性：

必选（三选一，决定传输类型）：

可选：

环境变量展开

Gemini CLI 会自动展开env块中的环境变量，让你可以在不硬编码敏感信息的前提下引用 shell 或宿主环境中已定义的值。展开工具支持：

• POSIX/Bash 语法：$VARIABLE_NAME或${VARIABLE_NAME}（全平台）；
• Windows 语法：%VARIABLE_NAME%（仅在 Windows 上运行时支持）。

若变量在当前环境中未定义，则解析为空字符串。

"env": { "API_KEY": "$MY_EXTERNAL_TOKEN", "LOG_LEVEL": "$LOG_LEVEL", "TEMP_DIR": "%TEMP%" }

安全与环境脱敏（源码级解析）

为保护凭据，Gemini CLI 在派生 MCP 服务器进程时会执行环境脱敏（environment sanitization），其实现位于 environmentSanitization.ts：

自动脱敏。默认情况下，CLI 会从基础环境（继承自宿主进程）中删去敏感变量，防止宿主环境中的敏感信息（如 AWS 密钥、GitHub token）意外泄露给可能执行恶意代码或记录环境的第三方 MCP 服务器。结合源码可以确认具体规则：

• 核心项目密钥：GEMINI_API_KEY、GOOGLE_API_KEY等；
• 敏感名称模式（NEVER_ALLOWED_NAME_PATTERNS）：匹配TOKEN、SECRET、PASSWORD、PASSWD、KEY、AUTH、CREDENTIAL、CREDS、PRIVATE、CERT的名称一律脱敏；
• 敏感值模式（NEVER_ALLOWED_VALUE_PATTERNS）：私钥/证书 PEM 头、URL 内嵌凭据、GitHub token（ghp_、github_pat_等前缀）、Google API key（AIzaSy...）、AWS Access Key（AKIA...）、JWT、Stripe 与 Slack token 等；
• 永不放行名单（NEVER_ALLOWED_ENVIRONMENT_VARIABLES）：DATABASE_URL、CONNECTION_STRING、DB_URI、CLIENT_ID、AZURE_CLIENT_ID、SLACK_WEBHOOK_URL等即使显式声明也不从基础环境继承；
• 以GEMINI_CLI_或GIT_CONFIG_为前缀的变量始终放行，基础系统变量（PATH、HOME、TEMP、TERM等，见 ALWAYS_ALLOWED_ENVIRONMENT_VARIABLES）不受影响；
• 在 CI 环境（检测到GITHUB_SHA或SURFACE=Github）下进入严格脱敏模式：除白名单变量外，其余环境一律剔除。

显式覆盖。若某个环境变量确实需要传给 MCP 服务器，必须在settings.json（或标准 MCP 客户端 / 远程技能场景下的mcp_config.json）该服务器的env属性中显式声明。显式定义的变量（含来自扩展的）被视为“用户知情同意”，不会被自动脱敏流程处理。

注意：即使允许显式声明，也应避免硬编码密钥。请使用环境变量展开（例如"MY_KEY": "$MY_KEY"）在运行时安全地从宿主环境取值。

示例：把 GitHub Token 安全地传给 GitHub 官方 MCP 服务器（通过mcp_config.json）

{ "mcpServers": { "github": { "command": "npx", "args": ["-y", "@github/github-mcp-server"], "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "$GITHUB_PERSONAL_ACCESS_TOKEN" } } } }

远程 MCP 服务器的 OAuth 支持

Gemini CLI 支持使用 SSE 或 HTTP 传输的远程 MCP 服务器的 OAuth 2.0 认证。

自动 OAuth 发现

对于支持 OAuth 发现的服务器，可以省略 OAuth 配置，让 CLI 自动发现：

{ "mcpServers": { "discoveredServer": { "url": "https://api.example.com/sse" } } }

CLI 会自动完成：检测服务器要求 OAuth（401 响应）、从服务器元数据发现 OAuth 端点、执行动态客户端注册（若支持）、处理 OAuth 流程与令牌管理。

认证流程

1. 首次连接以 401 Unauthorized 失败；
2. OAuth 发现找到授权端点与令牌端点；
3. 打开浏览器供用户认证（需要本地浏览器访问能力）；
4. 授权码换取访问令牌；
5. 令牌被安全存储以供后续使用；
6. 携带有效令牌重试连接成功。

重要：OAuth 认证要求本地机器能够打开浏览器，并能接收http://localhost:<随机端口>/oauth/callback上的重定向（若配置了redirectUri则为指定端口）。因此以下环境不可用：无浏览器的无头环境、无 X11 转发的远程 SSH 会话、无浏览器支持的容器环境。

管理 OAuth 认证

使用/mcp auth命令：

# 列出需要认证的服务器 /mcp auth # 为指定服务器认证 /mcp auth serverName # 令牌过期后重新认证 /mcp auth serverName

OAuth 配置属性

• enabled（boolean）：为该服务器启用 OAuth；
• clientId（string）：OAuth 客户端标识（支持动态注册时可省略）；
• clientSecret（string）：OAuth 客户端密钥（公共客户端可省略）；
• authorizationUrl（string）：授权端点（省略时自动发现）；
• tokenUrl（string）：令牌端点（省略时自动发现）；
• scopes（string[]）：所需 OAuth 作用域；
• redirectUri（string）：自定义重定向 URI（默认使用操作系统分配的随机端口，如http://localhost:<随机端口>/oauth/callback）；
• tokenParamName（string）：SSE URL 中令牌的查询参数名；
• audiences（string[]）：令牌有效的作用域受众。

令牌管理

OAuth 令牌自动完成：安全存储于~/.gemini/mcp-oauth-tokens.json、过期时刷新（如有 refresh token）、每次连接前校验、失效或过期时清理。

认证提供者类型（authProviderType）

• dynamic_discovery（默认）：CLI 从服务器自动发现 OAuth 配置；
• google_credentials：使用 Google 应用默认凭据（ADC）认证；使用该方式时必须指定所需作用域；
• service_account_impersonation：模拟 Google Cloud 服务账号认证，用于访问 IAP 受保护服务（专为 Cloud Run 服务设计）。

Google 凭据示例：

{ "mcpServers": { "googleCloudServer": { "httpUrl": "https://my-gcp-service.run.app/mcp", "authProviderType": "google_credentials", "oauth": { "scopes": ["https://www.googleapis.com/auth/userinfo.email"] } } } }

服务账号模拟。需设置authProviderType为service_account_impersonation并提供：

• targetAudience：目标 IAP 受保护应用上允许列表中的 OAuth Client ID；
• targetServiceAccount：要模拟的 Google Cloud 服务账号邮箱。

CLI 会利用本地 ADC 为指定服务账号与受众生成 OIDC ID 令牌，再用于向 MCP 服务器认证。配套的云侧准备工作包括：创建（或复用并共享）OAuth 2.0 Client ID、把该 ID 加入项目的 IAP 程序化访问允许列表（Cloud Run 尚不是gcloud iap支持的资源类型，需按项目白名单）、创建服务账号、把服务账号与用户都加入 Cloud Run 服务的 IAP 策略、为所有访问者授予roles/iam.serviceAccountTokenCreator等模拟权限，并启用项目的 IAM Credentials API。

配置示例汇总

Python MCP 服务器（stdio）

{ "mcpServers": { "pythonTools": { "command": "python", "args": ["-m", "my_mcp_server", "--port", "8080"], "cwd": "./mcp-servers/python", "env": { "DATABASE_URL": "$DB_CONNECTION_STRING", "API_KEY": "${EXTERNAL_API_KEY}" }, "timeout": 15000 } } }

Node.js MCP 服务器（stdio）

{ "mcpServers": { "nodeServer": { "command": "node", "args": ["dist/server.js", "--verbose"], "cwd": "./mcp-servers/node", "trust": true } } }

基于 Docker 的 MCP 服务器

{ "mcpServers": { "dockerizedServer": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "API_KEY", "-v", "${PWD}:/workspace", "my-mcp-server:latest" ], "env": { "API_KEY": "$EXTERNAL_SERVICE_TOKEN" } } } }

HTTP 服务器 / 带自定义请求头的 HTTP 服务器

{ "mcpServers": { "httpServer": { "httpUrl": "http://localhost:3000/mcp", "timeout": 5000 } } }

{ "mcpServers": { "httpServerWithAuth": { "httpUrl": "http://localhost:3000/mcp", "headers": { "Authorization": "Bearer your-api-token", "X-Custom-Header": "custom-value", "Content-Type": "application/json" }, "timeout": 5000 } } }

带工具过滤的 MCP 服务器

{ "mcpServers": { "filteredServer": { "command": "python", "args": ["-m", "my_mcp_server"], "includeTools": ["safe_tool", "file_reader", "data_processor"], "excludeTools": ["dangerous_tool", "file_deleter"], "timeout": 30000 } } }

SSE 服务器 + 服务账号模拟

{ "mcpServers": { "myIapProtectedServer": { "url": "https://my-iap-service.run.app/sse", "authProviderType": "service_account_impersonation", "targetAudience": "YOUR_IAP_CLIENT_ID.apps.googleusercontent.com", "targetServiceAccount": "your-sa@your-project.iam.gserviceaccount.com" } } }

发现过程深入解析

Gemini CLI 启动时按如下流程完成 MCP 服务器发现：

1. 服务器遍历与连接

对mcpServers中的每个服务器：

1. 状态置为CONNECTING；
2. 按配置选择传输：httpUrl→StreamableHTTPClientTransport，url→SSEClientTransport，command→StdioClientTransport；
3. 在配置超时内尝试连接；
4. 失败则记录日志并把状态置为DISCONNECTED。

2. 工具发现

连接成功后：调用服务器工具列表端点 → 校验每个工具声明 → 按includeTools/excludeTools过滤 → 名称消毒以适配 Gemini API 要求：

• 字母、数字、下划线（_）、连字符（-）、点（.）、冒号（:）以外的字符被替换为下划线；
• 超过 63 字符的名称会截断并在中间插入省略号（...）。

3. 工具命名与命名空间

为防止多服务器之间或与内置工具冲突，每个 MCP 工具都会无条件获得全限定名（FQN），格式为mcp_{serverName}_{toolName}；工具注册表维护 FQN 与原始服务器标识的元数据映射。若两个服务器使用相同别名且暴露同名工具，后注册者覆盖前者。要为 MCP 工具配置权限（自动批准或拒绝）等策略，参见 Policy Engine 文档中的 MCP 工具专用语法。

警告：MCP 服务器名称中不要使用下划线（用my-server而非my_server）。策略解析器在mcp_前缀之后按第一个下划线切分 FQN（mcp_server_tool）；若服务器名含下划线，解析器会误判服务器身份，导致通配规则和安全策略静默失效。

4. Schema 处理

工具参数 schema 会经过消毒以适配 Gemini API：移除$schema属性、剥离additionalProperties、去掉anyOf中的default值（Vertex AI 兼容）、并对嵌套 schema 递归处理。

5. 连接管理

发现完成后：成功注册工具的服务器保持持久连接；未提供任何可用工具的服务器关闭连接；最终状态置为CONNECTED或DISCONNECTED。这与源码 connectAndDiscover() 的行为一致：prompts 与 tools 均为空即抛出错误并在 catch 分支中close()客户端，否则注册后调用toolRegistry.sortTools()稳定排序。

工具执行流程

当模型决定使用某个 MCP 工具时：

1. 工具调用

模型生成FunctionCall，包含：注册名（可能带前缀）的工具名 + 匹配工具参数 schema 的 JSON 参数对象。

2. 确认流程

DiscoveredMCPToolInvocation 实现了多层确认逻辑：

基于信任的跳过：当trust为真时不需要确认。源码中的实际条件是（mcp-tool.ts）：

if (this.cliConfig?.isTrustedFolder() && this.trust) { return false; // server is trusted, no confirmation needed }

从源码看，信任跳过还有一个前提：当前目录必须是受信任目录（trusted folder）。这是一个文档未强调的安全细节——即使配置了trust: true，在未信任文件夹中仍然会触发确认。

动态白名单：系统维护两级内部白名单——服务器级（serverName，信任其全部工具）与工具级（serverName.toolName，信任特定工具）。

用户选择：需要确认时，用户可以选择：仅本次执行 / 始终允许此工具 / 始终允许此服务器 / 取消。

3. 执行

确认通过（或信任跳过）后：参数对照 schema 校验 → 底层CallableTool以原始服务器工具名发起 MCP 调用：

const functionCalls = [ { name: this.serverToolName, // 原始服务器工具名 args: params, }, ];

→ 响应被处理为 LLM 上下文与用户展示两种形态。

4. 响应处理

执行结果包含：

• llmContent：供模型上下文使用的原始响应 parts；
• returnDisplay：面向用户的格式化输出（常见为 markdown 代码块中的 JSON）。

如何与你的 MCP 服务器交互

使用/mcp命令

/mcp命令提供 MCP 配置的全面信息：服务器列表、连接状态（CONNECTED/CONNECTING/DISCONNECTED）、服务器配置摘要（不含敏感数据）、每个服务器的可用工具及描述、整体发现状态。

示例输出：

MCP Servers Status: 📡 pythonTools (CONNECTED) Command: python -m my_mcp_server --port 8080 Working Directory: ./mcp-servers/python Timeout: 15000ms Tools: calculate_sum, file_analyzer, data_processor 🔌 nodeServer (DISCONNECTED) Command: node dist/server.js --verbose Error: Connection refused 🐳 dockerizedServer (CONNECTED) Command: docker run -i --rm -e API_KEY my-mcp-server:latest Tools: mcp_dockerizedServer_docker_deploy, mcp_dockerizedServer_docker_status Discovery State: COMPLETED

工具使用

工具被发现后，对模型而言与内置工具无异。模型会自动：基于请求选择合适工具 →（服务器不受信任时）展示确认对话框 → 以正确参数执行 → 以用户友好的形式展示结果。

状态监控与故障排查

覆盖扩展提供的服务器配置

若 MCP 服务器由扩展（例如google-workspace扩展）提供，你仍可在本地settings.json中覆盖其设置。Gemini CLI 会把本地配置与扩展默认值合并：

• 工具列表按“最严格策略胜出”合并：excludeTools取并集（任一方屏蔽即禁用）；includeTools取交集（双方都提供白名单时，只有同时出现在两份列表中的工具才启用；只有一方提供白名单时尊重该方）；excludeTools始终优先于includeTools。这保证你对扩展工具始终拥有否决权，且扩展无法重新启用你从个人白名单中剔除的工具；
• 环境变量：两个env对象合并，同名变量本地值优先；
• 标量属性：command、url、timeout等由本地值覆盖。

{ "mcpServers": { "google-workspace": { "excludeTools": ["gmail.send"] } } }

连接状态

• 服务器状态（MCPServerStatus）：DISCONNECTED（未连接或有错误）、CONNECTING（连接中）、CONNECTED（已连接就绪）；
• 发现状态（MCPDiscoveryState）：NOT_STARTED、IN_PROGRESS、COMPLETED（无论有无错误）。

常见问题与解决方案

服务器无法连接（状态DISCONNECTED）：检查command/args/cwd是否正确 → 手动直接运行服务器命令验证 → 确认依赖已安装 → 查看 CLI 输出的错误信息 → 验证 CLI 有权限执行该命令。

未发现工具（已连接但无工具）：确认服务器确实注册了工具 → 确认其正确实现了 MCP 工具列表方法 → 检查服务器 stderr 中的错误 → 手动测试服务器的工具发现端点。

工具不执行（已发现但执行失败）：确认工具接受预期参数 → 校验 input schema 是合法 JSON Schema → 检查工具是否抛出未处理异常 → 考虑调大timeout。

沙箱兼容性（启用沙箱后失败）：使用内置全部依赖的 Docker 容器服务器 → 确保服务器可执行文件在沙箱内可访问 → 配置沙箱允许所需网络连接 → 确认所需环境变量被传递。

调试技巧

1. 用--debug启动 CLI 获得详细输出（交互模式下按 F12 打开调试控制台）；
2. MCP 服务器 stderr 会被捕获并记录（过滤 INFO 消息）；
3. 先独立测试 MCP 服务器再集成；
4. 从简单工具开始，逐步增加复杂功能；
5. 开发期间频繁使用/mcp监控状态。

重要注意事项

安全考量

• 信任设置：trust会绕过所有确认对话框，务必谨慎，只用于你完全控制的服务器（并注意上文提到的“受信任文件夹”前提）；
• 访问令牌：配置含 API key 或 token 的环境变量时保持安全意识，参见上文环境脱敏小节；
• 沙箱兼容：使用沙箱时确保 MCP 服务器在沙箱环境内可用；
• 私有数据：宽范围的个人访问令牌可能导致跨仓库信息泄露。

性能与资源管理

• 连接持久化：成功注册工具的服务器保持持久连接；
• 自动清理：不提供工具的服务器连接自动关闭；
• 超时管理：按服务器响应特征配置合理超时；
• 资源监控：MCP 服务器作为独立进程运行，会消耗系统资源。

Schema 兼容性

• 系统自动移除$schema、additionalProperties等属性以适配 Gemini API；
• 工具名自动消毒以符合 API 要求；
• 服务器之间的工具名冲突通过自动加前缀解决。

从工具返回富内容

MCP 工具不限于返回纯文本——可以在单次工具响应中返回文本、图片、音频及其他二进制数据的富多部件内容，让模型在一轮内获得多样化信息。所有返回数据都会作为下一轮生成的上下文发送给模型，供其推理或总结。

工作原理：工具的响应需符合 MCP 规范中CallToolResult的格式，content字段是ContentBlock对象数组。Gemini CLI 会解析该数组，把文本与二进制数据分离并打包给模型。支持的 block 类型包括：text、image、audio、resource（嵌入式内容）、resource_link，可混用。

示例：同时返回文本与图片的 JSON 响应

{ "content": [ { "type": "text", "text": "Here is the logo you requested." }, { "type": "image", "data": "BASE64_ENCODED_IMAGE_DATA_HERE", "mimeType": "image/png" }, { "type": "text", "text": "The logo was created in 2025." } ] }

收到该响应后，Gemini CLI 会：1）提取全部文本合并为单个functionResponsepart 供模型使用；2）把图片数据作为独立的inlineDatapart；3）在 CLI 中给出简洁的用户摘要，提示同时收到了文本与图片。由此你可以构建向 Gemini 模型提供富多模态上下文的复杂工具。

把 MCP prompts 用作斜杠命令

除了工具，MCP 服务器还能暴露预定义 prompts，在 Gemini CLI 中作为斜杠命令执行，为常见或复杂查询创建快捷方式。

在服务器上定义 prompts

一个 stdio MCP 服务器的示例：

import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { z } from 'zod'; const server = new McpServer({ name: 'prompt-server', version: '1.0.0', }); server.registerPrompt( 'poem-writer', { title: 'Poem Writer', description: 'Write a nice haiku', argsSchema: { title: z.string(), mood: z.string().optional() }, }, ({ title, mood }) => ({ messages: [ { role: 'user', content: { type: 'text', text: `Write a haiku${mood ? ` with the mood ${mood}` : ''} called ${title}. Note that a haiku is 5 syllables followed by 7 syllables followed by 5 syllables `, }, }, ], }), ); const transport = new StdioServerTransport(); await server.connect(transport);

在settings.json的mcpServers下注册：

{ "mcpServers": { "nodeServer": { "command": "node", "args": ["filename.ts"] } } }

调用 prompts

发现后，直接以 prompt 名作为斜杠命令调用，CLI 自动解析参数（支持具名参数或位置参数）：

/poem-writer --title="Gemini CLI" --mood="reverent"

/poem-writer "Gemini CLI" reverent

执行时，Gemini CLI 对该服务器调用prompts/get并传入参数；服务器负责把参数代入 prompt 模板并返回最终 prompt 文本，CLI 再将其发送给模型执行。这是自动化与共享常用工作流的便捷方式。源码对应实现为 invokeMcpPrompt()，它会把参数统一转为字符串后调用 MCP 的prompts/get方法。

用gemini mcp命令组管理服务器

除了手动编辑settings.json，Gemini CLI 提供命令组来程序化管理服务器配置。

添加服务器（gemini mcp add）

gemini mcp add [options] <name> <commandOrUrl> [args...]

• <name>：服务器唯一名称；
• <commandOrUrl>：stdio 的执行命令或 http/sse 的 URL；
• [args...]：stdio 命令的可选参数。

选项（flags）：

• -s, --scope：配置作用域（user 或 project），默认project。用户级写入~/.gemini/settings.json，项目级写入.gemini/settings.json；
• -t, --transport：传输类型（stdio、sse、http），默认stdio；
• -e, --env：设置环境变量（如-e KEY=value）；
• -H, --header：为 SSE/HTTP 传输设置请求头（如-H "X-Api-Key: abc123" -H "Authorization: Bearer abc123"）；
• --timeout：连接超时（毫秒）；
• --trust：信任该服务器（跳过所有工具调用确认）；
• --description：服务器描述；
• --include-tools：逗号分隔的待包含工具列表；
• --exclude-tools：逗号分隔的待排除工具列表。

添加 stdio 服务器（本地服务器的默认传输）：

# 基本语法 gemini mcp add [options] <name> <command> [args...] # 示例：添加本地服务器 gemini mcp add -e API_KEY=123 -e DEBUG=true my-stdio-server /path/to/server arg1 arg2 arg3 # 示例：添加本地 python 服务器 gemini mcp add python-server python server.py -- --server-arg my-value

添加 HTTP 服务器（streamable HTTP 传输）：

gemini mcp add --transport http http-server https://api.example.com/mcp/ gemini mcp add --transport http --header "Authorization: Bearer abc123" secure-http https://api.example.com/mcp/

添加 SSE 服务器：

gemini mcp add --transport sse sse-server https://api.example.com/sse/ gemini mcp add --transport sse --header "Authorization: Bearer abc123" secure-sse https://api.example.com/sse/

列出服务器（gemini mcp list）

gemini mcp list

显示每个服务器的名称、配置详情与连接状态，无 flags。

注意：出于安全考虑，stdio服务器（使用command属性）只有当前文件夹受信任时才会被实际测试并显示为 “Connected”；未信任文件夹下显示为 “Disconnected”。使用gemini trust信任当前文件夹。

示例输出：

✓ stdio-server: command: python3 server.py (stdio) - Connected ✓ http-server: https://api.example.com/mcp (http) - Connected ✗ sse-server: https://api.example.com/sse (sse) - Disconnected

移除服务器（gemini mcp remove）

gemini mcp remove <name>

选项：-s, --scope（user 或 project，默认project）。示例：gemini mcp remove my-server会从相应settings.json的mcpServers对象中删除该条目。

启用/禁用服务器（gemini mcp enable/gemini mcp disable）

临时禁用（保留配置）或重新启用服务器，无需删除配置：

gemini mcp enable <name> [--session] gemini mcp disable <name> [--session]

选项：--session仅对当前会话生效（不写入文件）。禁用后的服务器在/mcp中显示为 “Disabled”，不会连接、不提供工具；启用状态存储于~/.gemini/mcp-server-enablement.json。会话内也可用斜杠命令/mcp enable <name>与/mcp disable <name>。

诊断提示

为降低启动噪音，后台服务器的 MCP 连接错误默认静默。启动期检测到问题时仅提示一条信息：“MCP issues detected. Run /mcp list for status.”详细、可操作的诊断会在以下情况自动恢复：

1. 运行了/mcp list、/mcp auth等交互式命令；
2. 模型尝试执行该服务器的某个工具；
3. 调用了该服务器的 MCP prompt。

也可以在 shell 中运行gemini mcp list查看所有已配置服务器的连接错误。

服务器指令（Instructions）

Gemini CLI 支持 MCP 规范中的服务器指令（server instructions）：服务器在初始化结果（initialize result）中提供的 instructions 会被**追加到系统指令（system instructions）**中，用于向模型说明该服务器工具的用途与约定。

小结

这套集成的价值在于：settings.json提供声明式的多服务器、多传输配置能力（含工具黑白名单、环境变量安全展开与脱敏）；packages/core/src/tools/中的发现与执行层负责把任意 MCP 服务器安全地接入工具注册表（FQN 命名空间、schema 消毒、确认与信任机制）；gemini mcp命令组与/mcp斜杠命令则覆盖日常运维。三者配合，使 MCP 服务器成为在不触碰 CLI 源码的前提下扩展 Gemini CLI 能力的标准方式，同时通过环境脱敏、确认流程与策略引擎保留了明确的安全边界。

【免费下载链接】gemini-cliAn open-source AI agent that brings the power of Gemini directly into your terminal.项目地址: https://gitcode.com/GitHub_Trending/gemi/gemini-cli