Klavis CLI 深度解析用 klavis 命令在 Google Gemini CLI 中管理 Klavis MCP 服务器【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本文围绕 examples/google_gemini_cli-klavis/README.md 讲解 Klavis 官方提供的klavis命令行工具它能把 Klavis AI 托管的 MCPModel Context Protocol服务器一键注册、移除、列出或清空 Google Gemini CLI 的配置~/.gemini/settings.json并自动备份配置。读完本文你将掌握该工具的全部命令用法、写入配置的 JSON 结构以及 index.js 源码中参数解析、域名校验、备份与容错读取等关键实现细节。工具定位为什么需要 klavis CLIGemini CLI 通过~/.gemini/settings.json中的mcpServers字段加载 MCP 服务器。手工编辑该文件容易引入 JSON 语法错误且无法批量管理多个 Klavis 集成Gmail、Slack、Notion 等。klavisCLI 解决的就是这个问题自动定位并创建~/.gemini/settings.json配置目录修改前先自动备份只保留最近一份备份文件只管理域名包含klavis.ai的条目避免误删用户手工配置的其他 MCP 服务器对既有配置中的尾部逗号、未加引号键名等常见 JSON 瑕疵做了容错处理保留其余全部用户偏好与认证信息。README 的 What It Does 部分概括了四步工作流定位配置 → 备份 → 增删列清 → 保留既有偏好。下文先给出完整用法再结合源码逐层拆解。安装工具通过 npm 全局安装发布包名为klavisnpm install -g klavispackage.json 中声明了入口与运行环境约束{ name: klavis, version: 1.0.0, bin: { klavis: ./index.js }, engines: { node: 14.0.0 }, files: [index.js, README.md] }从 package.json#L8-L13 可见bin字段把klavis命令映射到 index.js该文件首行带有#!/usr/bin/env nodeshebang因此无需额外的构建或打包步骤engines要求 Node.js 14.0.0 及以上files字段说明发布产物只有入口脚本和 README 两个文件是一个零第三方依赖的单文件 CLI。命令总览与帮助klavis gemini --help源码中的 showHelp() 会输出完整帮助信息命令面固定为四种子命令加--help子命令语法说明添加klavis gemini add INSTANCE_URL把 Klavis MCP 实例 URL 注册进 Gemini 配置移除klavis gemini remove MCP_NAME按名称移除单个 Klavis MCP如gmail、slack、notion列出klavis gemini list显示当前已配置的所有 Klavis AI MCP 服务器清空klavis gemini clear --force移除所有 Klavis AI MCP必须携带--force安全旗标main() 的入参校验 对每个子命令都做了防御第一个位置参数必须是gemini第二个必须是add/remove/list/clear/help之一否则打印用法并以退出码 1 终止add与remove缺少第三个参数URL 或名称时直接报错clear未带--force时拒绝执行这是刻意的安全设计防止一次手滑清空所有集成。添加 MCP 服务器add 子命令用法klavis gemini add INSTANCE_URLINSTANCE_URL是你在 Klavis 控制台中获得的 MCP 实例 URL。README 中给出的典型示例# 添加 Gmail MCP Server klavis gemini add https://gmail-mcp-server.klavis.ai/mcp/?instance_idyour-id # 添加 Slack MCP Server klavis gemini add https://slack-mcp-server.klavis.ai/mcp/?instance_idyour-id # 添加 Notion MCP Server klavis gemini add https://notion-mcp-server.klavis.ai/mcp/?instance_idyour-id参数约束源码印证add 分支的参数处理 施加了三道校验协议前缀URL 必须以http开头否则提示Invalid URL format域名格式用正则https?:\/\/([^.])\.klavis\.ai提取子域名例如gmail-mcp-server.klavis.ai提取出gmail-mcp-server并转小写作为mcpServers下的键名。不匹配该模式的 URL 会直接报错Expected pattern: https://SERVICE-mcp-server.klavis.ai/归属校验URL 必须包含klavis.ai该工具只接受 Klavis AI 的 MCP 服务器——这也是 README 中反复强调的 Only Klavis AI MCPs can be added with this tool 的落地位置。URL 中的instance_id查询参数是实例标识与 Klavis API 中 OAuth 流程的instance_id参数见 openapi.json 中的 Start OAuth flow 描述同属一套实例寻址体系实例 URL 的获取方式参见 Gemini CLI 官方配置指南中Get Strata Server URL一节的 Dashboard 操作步骤。写入配置的 JSON 结构执行add成功后源码 会把条目写入~/.gemini/settings.json的mcpServers下写入前自动调用createBackup{ mcpServers: { gmail: { command: npx, args: [mcp-remote, https://gmail-mcp-server.klavis.ai/mcp/?instance_idyour-id] } } }这里的关键设计是npx mcp-remote urlGemini CLI 以 stdio 方式启动本地子进程mcp-remote充当远程桥接器把 Klavis 托管的 HTTP MCP 端点转成本地 stdio 会话。因此运行环境除了 Node.js 之外首次使用时还需能访问 npm registry 拉取mcp-remote包。这与 Klavis 知识库中 Claude Code 的npx mcp-remote用法是同一套远程接入模式参见 claude_code.mdx。如果settings.json尚不存在getSettingsPath() 会先创建~/.gemini目录再操作文件因此首次add无需手工初始化。移除与清空remove / clear 子命令# 移除指定 MCP名称需与 mcpServers 中的键一致 klavis gemini remove gmail klavis gemini remove slack # 清空所有 Klavis AI MCP必须带 --force klavis gemini clear --force两个子命令的安全边界都由 isKlavisAiService() 划定它读取目标条目的args[1]即 URL 位置只有 URL 中包含klavis.ai才判定为 Klavis AI 服务remove先检查条目是否存在再检查它是否为 Klavis AI 服务非 Klavis 条目会被明确拒绝is not a Klavis AI service and cannot be removed with this tool从而保护了用户手工添加的其他 MCP 配置clear只遍历并删除 通过isKlavisAiService过滤出的条目其余mcpServers键原样保留若没有可清空的条目直接提示 configuration is already empty 并退出不产生任何写入。两者在修改前都会调用备份函数且clear的--force强制要求由命令行校验层保证。列出已配置服务器list 子命令klavis gemini listlist 分支 遍历mcpServers的所有键用isKlavisAiService过滤后按序号打印名称与总数。注意它只列出 Klavis AI 的条目不会暴露配置中其他来源的 MCP 名称——这与该工具只管 Klavis 集成的定位一致。若结果为空会提示使用klavis gemini add INSTANCE_URL添加。备份与 JSON 容错两个防错机制自动备份策略createBackup() 的行为细节值得注意备份文件命名为settings.json.bak.毫秒时间戳与配置同目录存放每次修改add、remove、clear前执行一次备份备份后清理旧备份仅保留最近 1 份按文件名中的时间戳降序排序删除其余清理过程出错时被静默忽略不影响主流程——备份是辅助能力不能反过来阻塞配置修改。这意味着误操作例如clear --force后立即发现删多了时可以用最近一份.bak文件恢复但只有一份历史快照多次操作后更早的状态不可找回。读取时的 JSON 修复settings 读取逻辑 在JSON.parse之前做两次正则清洗/(,(\s*[}\]])/g → $1删除}/]前的尾随逗号/(([{,]\s*)([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/g → $1$2:把未加引号的键名补上双引号。这是针对用户手工编辑settings.json时最常见的两类 JSON 瑕疵的容错。若清洗后仍解析失败工具会打印原始错误信息并提示手工修复配置文件而不是带着损坏状态继续写入——这一点保证了保留既有偏好承诺的可靠性。参数解析的实现index.js#L6-L19 的 parseArgs() 是一个极简的手写解析器以--开头的记为 flag若下一个参数不以-开头则作为该 flag 的值否则值为布尔true其余收集为位置参数。由此带来两个使用注意--force这类布尔旗标只能出现在位置参数之后解析且不与位置参数混用add的 URL 本身就是位置参数URL 中若含?instance_id...这类查询串不需要额外转义因为它整体作为一个 argv 元素传入。使用前提与限制综合 README 的 Requirements 部分 与源码行为适用前提与边界如下环境Node.js ≥ 14.0.0已安装 Google Gemini CLI或至少存在/可创建.gemini配置目录归属限制add只接受https://service.klavis.ai形态的 URLremove/clear/list只对 URL 含klavis.ai的条目生效安全约束clear必须带--force备份只保留最近 1 份运行时依赖配置写入后Gemini CLI 实际调用 MCP 时需要npx mcp-remote可用即机器需能执行 npx 并拉取该桥接包配置生效与手工修改~/.gemini/settings.json相同需要重启 Gemini CLI 才能加载新增的 MCP 服务器这一点在 Gemini CLI 官方配置指南的验证步骤中也有明确说明在 Gemini CLI 中执行/mcp命令查看工具加载情况。与手工配置流程的对照如果不使用klavisCLI等效的手工流程是在 Klavis Dashboard 授权目标服务器、复制服务器 URL然后把它以npx mcp-remote URL的形式追加进~/.gemini/settings.json的mcpServers完整手工步骤见 docs/knowledge-base/use-mcp-server/gemini_cli.mdx。klavis gemini add本质上把这条手工路径自动化了并额外提供了备份、Klavis 归属校验与批量清理能力。两者写入的配置结构完全一致因此可以混用手工添加的 Klavis 条目同样能被list看到、被remove移除前提是其args[1]位置包含klavis.ai的 URL。排障速查结合工具输出与官方排障建议常见问题定位如下Invalid URL formatadd传入的 URL 不是http(s)开头或域名不符合*.klavis.ai模式请从 Klavis Dashboard 重新复制完整实例 URLService not foundremove的名称必须与mcpServers中已有的键完全一致可先用klavis gemini list核对is not a Klavis AI service该条目 URL 中不含klavis.ai工具拒绝操作需手工编辑~/.gemini/settings.json处理Error reading existing settingssettings.json存在超出两种容错范围之外的 JSON 错误需按提示手工修复后重试添加后 Gemini CLI 中工具未出现核对 URL 拼写、检查网络连通性、确认 Klavis Dashboard 中认证有效并完全重启 Gemini CLI 后用/mcp查看加载状态参考 gemini_cli.mdx 的 Troubleshooting 一节。小结klavis是一个零依赖、单文件index.js的 npm CLI以add/remove/list/clear四个子命令覆盖 Gemini CLI 中 Klavis MCP 集成的全生命周期管理其实现上的三个要点——域名白名单isKlavisAiService、修改前滚动备份createBackup与读取时 JSON 容错——共同保证了只动 Klavis 条目、随时可回滚的行为边界。配合 README.md 中的命令示例与 Gemini CLI 配置指南即可在终端内完成从集成注册到验证使用/mcp的完整闭环。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Klavis CLI 深度解析：用 klavis 命令在 Google Gemini CLI 中管理 Klavis MCP 服务器
Klavis CLI 深度解析用 klavis 命令在 Google Gemini CLI 中管理 Klavis MCP 服务器【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis本文围绕 examples/google_gemini_cli-klavis/README.md 讲解 Klavis 官方提供的klavis命令行工具它能把 Klavis AI 托管的 MCPModel Context Protocol服务器一键注册、移除、列出或清空 Google Gemini CLI 的配置~/.gemini/settings.json并自动备份配置。读完本文你将掌握该工具的全部命令用法、写入配置的 JSON 结构以及 index.js 源码中参数解析、域名校验、备份与容错读取等关键实现细节。工具定位为什么需要 klavis CLIGemini CLI 通过~/.gemini/settings.json中的mcpServers字段加载 MCP 服务器。手工编辑该文件容易引入 JSON 语法错误且无法批量管理多个 Klavis 集成Gmail、Slack、Notion 等。klavisCLI 解决的就是这个问题自动定位并创建~/.gemini/settings.json配置目录修改前先自动备份只保留最近一份备份文件只管理域名包含klavis.ai的条目避免误删用户手工配置的其他 MCP 服务器对既有配置中的尾部逗号、未加引号键名等常见 JSON 瑕疵做了容错处理保留其余全部用户偏好与认证信息。README 的 What It Does 部分概括了四步工作流定位配置 → 备份 → 增删列清 → 保留既有偏好。下文先给出完整用法再结合源码逐层拆解。安装工具通过 npm 全局安装发布包名为klavisnpm install -g klavispackage.json 中声明了入口与运行环境约束{ name: klavis, version: 1.0.0, bin: { klavis: ./index.js }, engines: { node: 14.0.0 }, files: [index.js, README.md] }从 package.json#L8-L13 可见bin字段把klavis命令映射到 index.js该文件首行带有#!/usr/bin/env nodeshebang因此无需额外的构建或打包步骤engines要求 Node.js 14.0.0 及以上files字段说明发布产物只有入口脚本和 README 两个文件是一个零第三方依赖的单文件 CLI。命令总览与帮助klavis gemini --help源码中的 showHelp() 会输出完整帮助信息命令面固定为四种子命令加--help子命令语法说明添加klavis gemini add INSTANCE_URL把 Klavis MCP 实例 URL 注册进 Gemini 配置移除klavis gemini remove MCP_NAME按名称移除单个 Klavis MCP如gmail、slack、notion列出klavis gemini list显示当前已配置的所有 Klavis AI MCP 服务器清空klavis gemini clear --force移除所有 Klavis AI MCP必须携带--force安全旗标main() 的入参校验 对每个子命令都做了防御第一个位置参数必须是gemini第二个必须是add/remove/list/clear/help之一否则打印用法并以退出码 1 终止add与remove缺少第三个参数URL 或名称时直接报错clear未带--force时拒绝执行这是刻意的安全设计防止一次手滑清空所有集成。添加 MCP 服务器add 子命令用法klavis gemini add INSTANCE_URLINSTANCE_URL是你在 Klavis 控制台中获得的 MCP 实例 URL。README 中给出的典型示例# 添加 Gmail MCP Server klavis gemini add https://gmail-mcp-server.klavis.ai/mcp/?instance_idyour-id # 添加 Slack MCP Server klavis gemini add https://slack-mcp-server.klavis.ai/mcp/?instance_idyour-id # 添加 Notion MCP Server klavis gemini add https://notion-mcp-server.klavis.ai/mcp/?instance_idyour-id参数约束源码印证add 分支的参数处理 施加了三道校验协议前缀URL 必须以http开头否则提示Invalid URL format域名格式用正则https?:\/\/([^.])\.klavis\.ai提取子域名例如gmail-mcp-server.klavis.ai提取出gmail-mcp-server并转小写作为mcpServers下的键名。不匹配该模式的 URL 会直接报错Expected pattern: https://SERVICE-mcp-server.klavis.ai/归属校验URL 必须包含klavis.ai该工具只接受 Klavis AI 的 MCP 服务器——这也是 README 中反复强调的 Only Klavis AI MCPs can be added with this tool 的落地位置。URL 中的instance_id查询参数是实例标识与 Klavis API 中 OAuth 流程的instance_id参数见 openapi.json 中的 Start OAuth flow 描述同属一套实例寻址体系实例 URL 的获取方式参见 Gemini CLI 官方配置指南中Get Strata Server URL一节的 Dashboard 操作步骤。写入配置的 JSON 结构执行add成功后源码 会把条目写入~/.gemini/settings.json的mcpServers下写入前自动调用createBackup{ mcpServers: { gmail: { command: npx, args: [mcp-remote, https://gmail-mcp-server.klavis.ai/mcp/?instance_idyour-id] } } }这里的关键设计是npx mcp-remote urlGemini CLI 以 stdio 方式启动本地子进程mcp-remote充当远程桥接器把 Klavis 托管的 HTTP MCP 端点转成本地 stdio 会话。因此运行环境除了 Node.js 之外首次使用时还需能访问 npm registry 拉取mcp-remote包。这与 Klavis 知识库中 Claude Code 的npx mcp-remote用法是同一套远程接入模式参见 claude_code.mdx。如果settings.json尚不存在getSettingsPath() 会先创建~/.gemini目录再操作文件因此首次add无需手工初始化。移除与清空remove / clear 子命令# 移除指定 MCP名称需与 mcpServers 中的键一致 klavis gemini remove gmail klavis gemini remove slack # 清空所有 Klavis AI MCP必须带 --force klavis gemini clear --force两个子命令的安全边界都由 isKlavisAiService() 划定它读取目标条目的args[1]即 URL 位置只有 URL 中包含klavis.ai才判定为 Klavis AI 服务remove先检查条目是否存在再检查它是否为 Klavis AI 服务非 Klavis 条目会被明确拒绝is not a Klavis AI service and cannot be removed with this tool从而保护了用户手工添加的其他 MCP 配置clear只遍历并删除 通过isKlavisAiService过滤出的条目其余mcpServers键原样保留若没有可清空的条目直接提示 configuration is already empty 并退出不产生任何写入。两者在修改前都会调用备份函数且clear的--force强制要求由命令行校验层保证。列出已配置服务器list 子命令klavis gemini listlist 分支 遍历mcpServers的所有键用isKlavisAiService过滤后按序号打印名称与总数。注意它只列出 Klavis AI 的条目不会暴露配置中其他来源的 MCP 名称——这与该工具只管 Klavis 集成的定位一致。若结果为空会提示使用klavis gemini add INSTANCE_URL添加。备份与 JSON 容错两个防错机制自动备份策略createBackup() 的行为细节值得注意备份文件命名为settings.json.bak.毫秒时间戳与配置同目录存放每次修改add、remove、clear前执行一次备份备份后清理旧备份仅保留最近 1 份按文件名中的时间戳降序排序删除其余清理过程出错时被静默忽略不影响主流程——备份是辅助能力不能反过来阻塞配置修改。这意味着误操作例如clear --force后立即发现删多了时可以用最近一份.bak文件恢复但只有一份历史快照多次操作后更早的状态不可找回。读取时的 JSON 修复settings 读取逻辑 在JSON.parse之前做两次正则清洗/(,(\s*[}\]])/g → $1删除}/]前的尾随逗号/(([{,]\s*)([a-zA-Z_$][a-zA-Z0-9_$]*)\s*:/g → $1$2:把未加引号的键名补上双引号。这是针对用户手工编辑settings.json时最常见的两类 JSON 瑕疵的容错。若清洗后仍解析失败工具会打印原始错误信息并提示手工修复配置文件而不是带着损坏状态继续写入——这一点保证了保留既有偏好承诺的可靠性。参数解析的实现index.js#L6-L19 的 parseArgs() 是一个极简的手写解析器以--开头的记为 flag若下一个参数不以-开头则作为该 flag 的值否则值为布尔true其余收集为位置参数。由此带来两个使用注意--force这类布尔旗标只能出现在位置参数之后解析且不与位置参数混用add的 URL 本身就是位置参数URL 中若含?instance_id...这类查询串不需要额外转义因为它整体作为一个 argv 元素传入。使用前提与限制综合 README 的 Requirements 部分 与源码行为适用前提与边界如下环境Node.js ≥ 14.0.0已安装 Google Gemini CLI或至少存在/可创建.gemini配置目录归属限制add只接受https://service.klavis.ai形态的 URLremove/clear/list只对 URL 含klavis.ai的条目生效安全约束clear必须带--force备份只保留最近 1 份运行时依赖配置写入后Gemini CLI 实际调用 MCP 时需要npx mcp-remote可用即机器需能执行 npx 并拉取该桥接包配置生效与手工修改~/.gemini/settings.json相同需要重启 Gemini CLI 才能加载新增的 MCP 服务器这一点在 Gemini CLI 官方配置指南的验证步骤中也有明确说明在 Gemini CLI 中执行/mcp命令查看工具加载情况。与手工配置流程的对照如果不使用klavisCLI等效的手工流程是在 Klavis Dashboard 授权目标服务器、复制服务器 URL然后把它以npx mcp-remote URL的形式追加进~/.gemini/settings.json的mcpServers完整手工步骤见 docs/knowledge-base/use-mcp-server/gemini_cli.mdx。klavis gemini add本质上把这条手工路径自动化了并额外提供了备份、Klavis 归属校验与批量清理能力。两者写入的配置结构完全一致因此可以混用手工添加的 Klavis 条目同样能被list看到、被remove移除前提是其args[1]位置包含klavis.ai的 URL。排障速查结合工具输出与官方排障建议常见问题定位如下Invalid URL formatadd传入的 URL 不是http(s)开头或域名不符合*.klavis.ai模式请从 Klavis Dashboard 重新复制完整实例 URLService not foundremove的名称必须与mcpServers中已有的键完全一致可先用klavis gemini list核对is not a Klavis AI service该条目 URL 中不含klavis.ai工具拒绝操作需手工编辑~/.gemini/settings.json处理Error reading existing settingssettings.json存在超出两种容错范围之外的 JSON 错误需按提示手工修复后重试添加后 Gemini CLI 中工具未出现核对 URL 拼写、检查网络连通性、确认 Klavis Dashboard 中认证有效并完全重启 Gemini CLI 后用/mcp查看加载状态参考 gemini_cli.mdx 的 Troubleshooting 一节。小结klavis是一个零依赖、单文件index.js的 npm CLI以add/remove/list/clear四个子命令覆盖 Gemini CLI 中 Klavis MCP 集成的全生命周期管理其实现上的三个要点——域名白名单isKlavisAiService、修改前滚动备份createBackup与读取时 JSON 容错——共同保证了只动 Klavis 条目、随时可回滚的行为边界。配合 README.md 中的命令示例与 Gemini CLI 配置指南即可在终端内完成从集成注册到验证使用/mcp的完整闭环。【免费下载链接】klavisKlavis AI: MCP integration platforms that let AI agents use tools reliably at any scale项目地址: https://gitcode.com/GitHub_Trending/kl/klavis创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考