指南 · 约 3 分钟

如何把 Onplana 连接到 Gemini CLI 和 Code Assist

一行安装。Onplana 在仓库根目录中提供了 Gemini 扩展清单，所以全部配置就是：gemini extensions install <repo>。

之后你就可以让 Gemini 做这样的事：“总结我在 Onplana 上的逾期任务”“为 Q3 发布创建一份带 5 个每周里程碑的项目计划”或“列出数据平台项目中我的团队成员”，Gemini 会直接在 Onplana 中执行。

打开 Onplana → 设置 → 智能体 GitHub 上的 Gemini CLI

简而言之：三条命令

# 1. Set your Onplana token
export ONPLANA_PAT=pat_paste-your-token-here

# 2. Install the extension
gemini extensions install https://github.com/Onplana/onplana-mcp-server

# 3. Restart and verify
gemini
> list my Onplana projects via the onplana tool

详细步骤见下文。

五个步骤详解

  1. 1

    安装 Gemini CLI（如果还没有）

    在 macOS / Linux 上：npm install -g @google/gemini-cli。在 Windows 上：在装有 Node 的控制台中运行同样的命令。用 `gemini --version` 确认。如果你在 VS Code 或 JetBrains 中使用 Gemini Code Assist，所需的一切已经就绪：Code Assist 与 CLI 共用配置文件。

  2. 2

    生成 Onplana 连接令牌

    在 app.onplana.com 登录 Onplana。前往“设置 → 智能体 → 连接智能体”，选择 Gemini CLI + Code Assist 卡片，然后选择“个人访问令牌”，最后生成令牌并显示连接片段。复制个人访问令牌（以 `pat_` 开头）。把它设为环境变量：export ONPLANA_PAT=pat_your-token-here（把这一行加到 ~/.bashrc 或 ~/.zshrc 中，让它保持生效）。

  3. 3

    安装 Onplana 的 Gemini 扩展（一条命令）

    运行：gemini extensions install https://github.com/Onplana/onplana-mcp-server。Onplana 的仓库在根目录中提供了 gemini-extension.json 清单，Gemini CLI 读取它来自动配置与 MCP 服务器的连接。或者，手动编辑 ~/.gemini/settings.json；格式说明见 developers.google.com/gemini-code-assist/docs。

  4. 4

    重启 Gemini CLI 或重新加载编辑器

    对 Gemini CLI：退出后重新打开 `gemini`。对 VS Code 中的 Gemini Code Assist：Cmd/Ctrl+Shift+P → "Developer: Reload Window"。对 JetBrains：重启 IDE。重启后，Onplana 的工具会出现在 /mcp 选择器中。

  5. 5

    确认连接

    在新的 Gemini 会话中问：“list my Onplana projects via the onplana tool”。Gemini 会调用 Onplana 的 list_projects 工具并显示结果。如果出现错误，请检查 Gemini 使用的环境中是否设置了 ONPLANA_PAT，并用 `gemini extensions list` 检查扩展清单是否已正确安装。

或者手动配置

如果你不想安装扩展，可以直接编辑~/.gemini/settings.json（或工作区根目录中的 .gemini/settings.json）：

{
  "mcpServers": {
    "onplana": {
      "httpUrl": "https://mcp.onplana.com/mcp",
      "headers": {
        "Authorization": "Bearer pat_paste-your-token-here"
      },
      "timeout": 5000
    }
  }
}

注意键名是 httpUrl，而不是 url。Gemini CLI 对 Onplana 这样的 Streamable HTTP 服务器使用 httpUrl，把 url 留给 SSE 服务器。headers.Authorization 中的 bearer 令牌为每个请求进行身份验证。

如何确认它能正常工作

打开一个新的 Gemini 会话，试试下面任意一个：

  • “用 onplana 工具列出我的项目。”
  • “显示分配给我的 Onplana 逾期任务。”
  • “在 Onplana 的项目 X 中创建一项名为‘把 Postgres 迁移到 Aurora’的任务。”
  • “在我的 Onplana 页面中搜索关于 API 迁移的笔记。”

运行 gemini extensions list 确认已安装 Onplana 扩展。安装成功后，/mcp 选择器应显示 Onplana 的完整工具列表。

常见问题

能在 VS Code 中的 Gemini Code Assist 里使用吗？

能。Gemini CLI 和 Gemini Code Assist 共用同一个配置文件（用户级的 ~/.gemini/settings.json，或工作区中的 .gemini/settings.json）。用 `gemini extensions install` 安装一次即可覆盖两者。然后重新加载 VS Code 窗口（Cmd/Ctrl+Shift+P → "Developer: Reload Window"），让 Code Assist 读取新配置。

gemini.google.com 上的 Gemini 应用呢？

截至 2026 年五月，gemini.google.com 仍不支持自定义 MCP 服务器。Google 引导想连接第三方 MCP 服务器的用户使用 Gemini CLI 或 Gemini Code Assist。我们在持续关注；如果该应用加入 MCP 支持，安装将通过类似 Claude.ai 的连接器界面一键完成。

Gemini Enterprise / Vertex AI Agent Builder 呢？

Gemini Enterprise 的配置与 Gemini CLI 不同：管理员在 Google Cloud 控制台中把 Onplana 添加为 Custom MCP Server 数据存储，需要 OAuth 客户端 ID 和 secret。它处于抢先体验阶段，由管理员管理，不是自助服务：Onplana 会应要求为你的组织签发客户端。docs.onplana.com/ai-agents/connect-onplana-to-gemini-enterprise/ 上的指南包含配置方法、最先开启的 20 项操作，以及申请访问的链接。

Onplana 的哪个方案包含 MCP？

MCP 包括免费版在内的所有方案均可使用。智能体的并发连接数随方案增加（Free 2，Professional 3，Business 5，Enterprise 10，Enterprise+ 不限），而真正限制 AI 用量的是你的 AI 令牌余额（付费方案为每月额度，Free 为一次性赠送额度，另加你购买的额度）。你可以随时在 app.onplana.com/billing 更换方案。

用 gemini-extension.json 安装和直接编辑 settings.json 有什么区别？

在功能上是等价的。安装扩展只需一条命令，并使用仓库根目录中的清单，因此可以重现。手动编辑 settings.json 适合你想把 Onplana 与多个 MCP 服务器（例如一个给 Onplana、一个给 Linear、一个给内部 API）放在同一个 `mcpServers` 对象中的情况。两种方式都可行，并共享同一份配置。

为什么键名叫 httpUrl 而不是 url？

Gemini CLI 区分通过 stdio 的 MCP 服务器（键：command）、通过 SSE 的（键：url）和通过 Streamable HTTP 的（键：httpUrl）。Onplana 的 MCP 服务器使用 Streamable HTTP，这是较新的传输标准，在普通 HTTPS 上处理请求和响应，无需 SSE。Claude Desktop、Cursor 和 ChatGPT 配置中的 `url` 键与之等效。

可以吊销连接吗？

可以，有两种方式：(1) Onplana → 设置 → 智能体 → 连接 → 在令牌所在行选择“吊销”。(2) 从环境中移除 ONPLANA_PAT，并运行 `gemini extensions uninstall onplana`。两者都立即生效；Gemini 的下一次工具调用会返回 401。

Gemini 能使用哪些工具？

351 个工具，与 Claude Desktop、Cursor 和 ChatGPT 得到的相同：读取（list_projects、list_my_tasks、get_task、search_org_knowledge 等）和写入（create_task、update_task、assign_task、create_milestone 等），以及治理、变更控制、合规、文档和工作流等领域。无论连接哪个客户端，目录都相同。部分工具由方案开启；完整目录见 onplana.com/mcp。

相关内容