Gemini CLI 接 MCP 连不上怎么办：配置文件位置与连接验证

小猫跳舞 技术创作者 2026-11-01 14 阅读

Gemini CLI 可通过 MCP 接入外部工具，并用配置文件或命令完成连接。

抓取时（2026-11-01），Gemini CLI 生态里的 MCP 接入方式已经同时覆盖本地进程和远程 HTTP 服务；但配置文件层级、传输类型和认证入口不同，混用后就会出现“配置写了却连不上”。本文就按这三层来：先把配置写进对的文件（含各客户端的路径对照），再确认传输类型选对（新版 mcp add 显式 --transport http，旧版会把裸 url 误当 SSE），最后逐层验证——服务器在不在列表、目录有没有被信任、认证走没走完。

MCP（Model Context Protocol，模型上下文协议）是一套连接规范：Gemini CLI 通过它发现外部服务器提供的工具，而服务器进程负责真正执行查询、文件操作或业务请求。

动手前准备三样东西

  1. 安装 Gemini CLI：执行 npx @google/gemini-cli 可免安装运行；需要长期使用时执行 npm install -g @google/gemini-cli。安装后可运行 gemini --version，能显示版本号即表示命令已可用。
  2. 准备 MCP 服务：远程服务至少要提供完整 URL，本地服务则要提供可执行文件或启动命令，并准备该服务要求的令牌。令牌不要直接写进项目文件；能通过 env 注入，就优先使用 env。
  3. 确认配置作用域：用户级配置会作用于所有项目，项目级配置只作用于当前目录。先决定作用范围，再选择配置方式，可避免换目录后工具突然消失。

Gemini CLI 的安装入口、命令和仓库说明见官方仓库。按官方当前说明，Gemini CLI 主要面向 Gemini Code Assist Standard、Enterprise、Code Assist for GitHub on Google Cloud，以及仍使用旧版付费 API 或 Vertex 密钥的用户；免费个人访问和 Google AI Pro、Ultra 已转向 Antigravity CLI。接入 MCP 不代表这些账号条件消失，认证方式仍以实际使用的 Gemini CLI 入口为准。

配置文件到底在哪

Gemini CLI 使用 mcpServers 对象保存服务器。用户级文件位于：

  • macOS、Linux：~/.gemini/settings.json
  • Windows：%USERPROFILE%.geminisettings.json

如果只想让一个项目使用 MCP，则在项目根目录创建 .gemini/settings.json。这一文件路径和 mcpServers 写法可对照 IONOS Cloud 的 Gemini CLI 接入文档。

配置方式 文件位置 适用范围 更适合谁
用户级 ~/.gemini/settings.json 当前用户的所有项目 经常切换项目、希望全局可用的个人开发者
项目级 项目根目录 .gemini/settings.json 仅当前项目 团队共享配置或只给当前仓库接工具
命令添加 由 gemini mcp add 写入上述文件 由 -s user 决定 不想手改 JSON、容易写错字段的人

用户级和项目级不是“备份与覆盖”的简单关系。常见预期是项目配置补上个人配置缺少的服务器，但具体合并行为不能仅凭文件名推断。因此，配置完成后必须进入目标项目实际启动 Gemini CLI，并检查工具是否出现。

远程 MCP：用一条命令添加

以 Celigo MCP 为例，其官方接入文档给出了可直接执行的命令：

gemini mcp add -s user --transport http celigo https://api.integrator.io/celigo-mcp

这里每个参数都有明确作用：

  • mcp add 表示添加 MCP 服务器；
  • celigo 是给服务器起的本地名称，之后认证时也要使用这个名字；
  • --transport http 明确选择 Streamable HTTP 传输；
  • -s user 把配置写入用户级 ~/.gemini/settings.json；
  • 最后的 URL 是 Celigo MCP 服务地址。

完整命令和作用域说明见 Celigo Developer Platform 的 Gemini 接入页。如果去掉 -s user，Gemini CLI 会把服务器写入当前目录的 .gemini/settings.json，只供该项目使用。

添加后，执行下面的命令完成认证：

/mcp auth celigo

浏览器会打开 Celigo 登录页面。完成登录后，返回 Gemini CLI 会话。这里的 celigo 必须与添加服务器时使用的名称一致；如果添加时写了别的名字，认证命令也要同步替换。

这条路径适合“服务端已经部署好，只需拿到 URL”的场景。它省去了手写 mcpServers 的过程，同时显式指定 HTTP 传输，能避开新旧版本对裸 url 解析方式不同造成的问题。

本地 MCP：直接编辑 settings.json

本地 MCP 通常以子进程运行。以 IONOS Cloud MCP 为例，官方文档给出的配置形态是：

{
  "mcpServers": {
    "ionoscloud-mcp": {
      "command": "/usr/local/bin/ionoscloud-mcp",
      "env": {
        "IONOS_TOKEN": "your-api-token"
        }
    }
  }
}

Windows 或其他安装路径下，command 必须改成机器上的真实可执行文件路径，不能照抄 /usr/local/bin/ionoscloud-mcp。填写前可在终端直接运行该路径；能启动服务进程，才把它写进配置。

需要特别注意环境变量的传递范围。IONOS 文档明确指出：Gemini CLI 只会把 env 块中显式列出的环境变量传给 MCP 服务器进程，不会自动继承系统里的同名环境变量。这意味着“终端里明明有令牌，Gemini CLI 却说未认证”并不矛盾，缺少的就是配置中的 env 项。

另外，仓库或项目根目录中若已有 .gemini/settings.json，应把新服务器合并进现有的 mcpServers 对象，而不是另起一个同名对象。下面这种写法会丢掉原配置：

{
  "mcpServers": {
    "server-a": {},
    "mcpServers": {
      "server-b": {}
    }
  }
}

正确结构应保持一个顶层 mcpServers，其中并列放置各服务器：

{
  "mcpServers": {
    "server-a": {},
    "server-b": {}
  }
}

真实项目还要检查 JSON 语法。一个多余的逗号、末尾漏引号，都会让整个设置文件无法解析。使用支持 JSON 校验的编辑器保存后，再启动 Gemini CLI。

连上了怎么看：按三层状态判断

先确认命令层成功执行。运行 gemini mcp add ... 时，终端没有报告参数、权限或配置写入错误，才进入启动验证。然后从你准备使用 MCP 的项目目录启动 Gemini CLI，因为项目级配置只在该目录生效。

第二层看工具是否被发现。Gemini CLI 启动时会连接已登记的 MCP 服务器，并注册服务器提供的工具。Celigo 的接入流程明确包含浏览器认证，IONOS 文档则说明工具默认在启动时注册。因此，服务器条目写入成功但工具没有出现时，应优先检查：服务进程是否启动、command 是否存在、远程 URL 是否可访问，以及启动 Gemini CLI 时是否位于正确目录。

目录未被信任是最容易漏掉的一层。 Celigo 官方文档原文：Gemini CLI disables MCP servers, including user-level ones, in folders you have not trusted——未受信任的文件夹里，连用户级配置的服务器都会被禁用。验证方法是先跑：

gemini mcp list

若目标服务器显示为 Disabled 并带 untrusted-folder 警告，就在该文件夹里重新启动 gemini 并在提示时选择 Trust folder，或在会话中执行 /permissions trust。修好这一层再去看网络和认证，否则会把“没授权目录”误判成“配置写错了”。

版本先确认再排查。 本文核到的证据没有给出当前 Gemini CLI 的版本号，所以不要猜：先执行 gemini --version 记下版本，再对照 Celigo 文档关于旧版（把裸 url 当 SSE）与新版（显式 --transport http）的分界，决定是补参数还是升级。

第三层看认证是否完成。以 Celigo 为例，/mcp auth celigo 应打开登录页，并允许你完成身份验证。认证后回到会话，调用一个只读、低风险的工具，确认 Gemini 不只是“看见配置”，而是真的能把请求交给 MCP 服务器。

可以按下面的可观察结果判断：

检查位置 成功标志 失败时先查
终端 mcp add 执行完成且未报错 命令拼写、服务名称、URL
配置文件 mcpServers 中出现对应服务器 JSON 逗号与引号、文件所在目录
Gemini 会话 服务器提供的工具可被发现 本地进程路径、远程服务状态
认证流程 /mcp auth celigo 能打开登录页并完成 服务名称、浏览器回调
工具调用 Gemini 成功调用一个只读工具并返回结果 令牌权限、环境变量、网络

三个常见卡点

旧版本把 HTTP 服务当成 SSE。 Celigo 文档明确提醒：旧版 Gemini CLI 会把未注明类型的裸 url 读成 SSE 传输，因此连接可能直接失败。解决方式不是反复改 URL，而是升级 Gemini CLI，并在添加命令中显式写出 --transport http。这说明配置文件里“看起来一样”的 url，在不同版本中未必代表相同传输。

令牌在终端中可见，服务端却收不到。 这是环境变量没有显式传递的典型表现。把服务要求的变量加入该服务器的 env 块，保存配置后重新启动 Gemini CLI。涉及敏感令牌时，还应检查文件是否被提交到 Git；只在本地试验时，可以把 .gemini/settings.json 排除出版本控制，但项目共享配置需要改用团队约定的凭据管理方式。

换目录后 MCP 消失。 如果用的是命令添加且没有 -s user，配置写在当前目录的 .gemini/settings.json；之后从别的目录启动，自然不会加载它。处理方式有两种：在目标项目重新执行添加命令，或者明确改用用户级配置。两种都能解决问题，但前者隔离项目，后者减少重复配置。

MCP 服务自身的安装说明也会影响连接。以 k8s-helm-mcp 为例，它的包说明里提供的配置包含 mcpServers 和实际启动参数，可用来核对“配置文件应该长什么样”（npm 官网页面对机器访问返回 403，用 npm view k8s-helm-mcp readme 直接在终端查看同一份说明）。不过第三方页面的配置示例不能替代 Gemini CLI 官方约定；最终仍应让服务器名、命令、参数和环境变量彼此对应。

配置前的最后取舍

远程 HTTP 服务优先用 gemini mcp add，因为命令能明确记录传输类型和作用域，也减少手写 JSON 的错误。本地子进程适合需要直接访问本机文件、二进制工具或离线服务的场景，此时用 command、args 和 env 表达启动方式。无论选哪一种，都应从低风险工具开始验证，并记录最终生成的 mcpServers 配置。

官方仓库用于核对安装方式和项目当前状态：https://github.com/google-gemini/gemini-cli。远程 HTTP 的完整命令可查 Celigo 接入页：https://developer.celigo.com/mcp/connect/gemini。本地服务器、配置文件路径和环境变量注意事项可查 IONOS Cloud 文档：https://docs.ionos.com/cloud/ai/mcp-server/connect-to-an-ai-client/gemini-cli。

# AI# 知识

评论区

0 条评论

登录后可评论。

小猫跳舞 14 阅读