PicoClaw MCP Server CLI 完全指南：用 `picoclaw mcp` 管理 MCP 服务器配置

PicoClaw MCP Server CLI 完全指南用picoclaw mcp管理 MCP 服务器配置【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclawPicoClaw 内置了mcp命令组用于在config.json中管理 MCPModel Context Protocol服务器条目。本文以 docs/reference/mcp-cli.md 为骨架结合 cmd/picoclaw/internal/mcp 与 pkg/config/config.go 的源码实现系统讲解picoclaw mcp add / remove / list / show / test / edit六个子命令的完整用法、参数解析规则、秘密处理方式与推荐工作流帮助你熟练地通过 CLI 完成 MCP 服务器的增删改查与连通性验证。定位它是配置管理器而不是服务器守护进程picoclaw mcp命令组扮演的是配置管理器角色有明确的责任边界它负责在tools.mcp.servers下新增、更新、删除并校验 MCP 服务器条目它不会自己维持 MCP 服务器的运行真正把配置的服务器启动起来的是 PicoClaw 的 gateway / host 进程——只要 MCP 功能启用宿主机就会按配置拉起这些服务器。从源码看命令组由 cmd/picoclaw/internal/mcp/command.go 中的NewMCPCommand()定义注册了add、remove、list、edit、test、show六个子命令且父命令不接受位置参数cobra.NoArgs直接运行会打印帮助。写入位置与写入策略CLI 更新的是与 PicoClaw 其余部分相同的配置文件路径解析逻辑见 cmd/picoclaw/internal/helpers.go 的GetConfigPath()若设置了环境变量PICOCLAW_CONFIG则使用该路径否则使用默认路径~/.picoclaw/config.json实际由config.GetHome()计算见同文件的GetConfigPath。每次写入时saveValidatedConfig见 cmd/picoclaw/internal/mcp/helpers.go会依次执行规范化对每个服务器的type字段调用config.NormalizeMCPTransportType做归一化例如把streamable-http归一为统一形式原子化保存通过config.SaveConfig写入避免中途崩溃留下半个文件写前校验先将配置序列化为 JSON再使用内嵌的 JSON SchemamcpConfigSchemaJSON同样定义在 helpers.go 中校验结构。该 Schema 明确了每条服务器记录的允许字段enabled必填、deferred、command、args、env、env_file、type枚举stdio/http/sse、url、headers并且command与url二者至少出现其一anyOf多余字段会被拒绝additionalProperties: false。这保证了 CLI 与手写配置遵循同一套约束。两个值得注意的行为picoclaw mcp add ...会自动把tools.mcp.enabled置为true见 add.go当picoclaw mcp remove ...删除的是最后一个服务器时会自动把tools.mcp.enabled置为false见 remove.go。快速开始以下是官方文档给出的六种典型添加场景覆盖 stdio 与远程传输# 1. 通过 npx 添加 stdio 服务器 picoclaw mcp add filesystem -- npx -y modelcontextprotocol/server-filesystem /tmp # 2. 带环境变量的 stdio 服务器值直接写入配置 picoclaw mcp add github --env GITHUB_PERSONAL_ACCESS_TOKENghp_xxx -- npx -y modelcontextprotocol/server-github # 3. 用 env 文件保存秘密推荐用于敏感信息 picoclaw mcp add github --env-file .env.github -- npx -y modelcontextprotocol/server-github # 4. 远程 HTTP 服务器 picoclaw mcp add context7 --transport http https://mcp.context7.com/mcp # 5. 带认证头的远程服务器flag 可以放在 URL 之后 picoclaw mcp add apify https://mcp.apify.com/ -t http --header Authorization: Bearer OMITTED # 6. 显式使用 -- 分隔符避免服务器参数与 CLI flag 混淆 picoclaw mcp add --transport stdio --env AIRTABLE_API_KEYYOUR_KEY airtable -- npx -y airtable-mcp-server添加完成后的检查三板斧picoclaw mcp list # 查看所有已配置条目 picoclaw mcp list --status # 实时探测每个已启用服务器的连通性 picoclaw mcp show filesystem # 查看单个服务器的完整细节与暴露的工具 picoclaw mcp test filesystem # 只做连通性探测 picoclaw mcp edit # 直接用 $EDITOR 打开原始配置做高级编辑命令总览命令用途picoclaw mcp add name [flags] command-or-url [args...]新增或更新一个 MCP 服务器条目picoclaw mcp remove name从配置中移除一个服务器条目picoclaw mcp list列出已配置的 MCP 服务器picoclaw mcp show name展示单个服务器的完整详情与工具列表picoclaw mcp test name尝试连接某个已配置的服务器picoclaw mcp edit用$EDITOR打开config.jsonpicoclaw mcp add详解语法与支持的 flagpicoclaw mcp add name [flags] command-or-url [args...]Flag含义--env,-e为 stdio 服务器添加环境变量格式KEYvalue可重复使用。解析后的值会直接存进配置--env-file为 stdio 服务器挂载 env 文件路径。推荐用于不想以明文内联进config.json的秘密--header,-H添加 HTTP 头格式Name: Value或NameValue可重复使用--transport,-t传输类型stdio默认、http/streamable-http、sse--force,-f覆盖已存在的条目跳过确认提示--deferred标记服务器为延迟deferred模式工具隐藏按需发现--no-deferred标记服务器为非延迟模式工具始终加载进上下文关于deferred的语义需要特别说明当既不传--deferred也不传--no-deferred时存储的配置中会省略deferred字段Deferred *bool为 nil运行时由全局discovery.enabled决定。只有当显式指定时该服务器才会生成独立的覆盖值。这一逻辑在 list.go 与 show.go 的buildServerInfo中都有体现deferredExplicit : server.Deferred ! nil显式值时优先取服务器自身值否则回落到全局配置。两种解析形式picoclaw mcp add [flags] name command-or-url [args...] picoclaw mcp add [flags] name -- command [args...]add子命令设置了DisableFlagParsing: true由parseAddArgs见 add.go手动解析参数因此规则比较灵活但也需要理解CLI flag 可以出现在名字之前、名字与目标之间甚至远程传输时出现在 URL 之后支持--transporthttp、--envKEYval这类形式对于stdio最稳健的写法是-- command [args...]--之后的所有内容都按命令与参数处理当 stdio 命令自身的参数可能看起来像 PicoClaw CLI flag 时务必使用--分隔符否则这些参数会被parseAddArgs当作 PicoClaw 的 flag 吞掉不使用--时前两个非 flag 词法单元被当作name和command-or-url其后的内容归入[args...]若已收集满两个位置参数后遇到-开头的 token则剩余部分整体并入服务器参数见 add.go。秘密处理--env与--env-file的选择--env KEYvalue会把解析后的值直接写入config.json解析逻辑见 helpers.go 的parseEnvAssignments按切分key 去空白且不允许为空。适合非敏感配置当值敏感、希望留在主配置文件之外时改用--env-file。CLI 只把 env 文件路径写入env_file字段由运行时读取文件加载环境变量。注意--env与--env-file仅对stdio传输有效对http/sse使用会被buildServerConfig明确拒绝并报错见 add.go。存储结果示例以picoclaw mcp add sqlite npx -y modelcontextprotocol/server-sqlite --db ./mydb.db为例写入配置的结果为{ tools: { mcp: { enabled: true, servers: { sqlite: { enabled: true, type: stdio, command: npx, args: [-y, modelcontextprotocol/server-sqlite, --db, ./mydb.db] } } } } }同样的命令加上--deferred后条目会多出deferred字段{ sqlite: { enabled: true, type: stdio, command: npx, args: [-y, modelcontextprotocol/server-sqlite, --db, ./mydb.db], deferred: true } }这里type、command、args、env、env_file、url、headers等字段的结构定义与 pkg/config/config.go 中的MCPServerConfig一一对应deferred字段带omitempty且为指针类型这正是不显式指定时省略该字段的底层原因。各传输类型的规则矩阵stdiocommand-or-url视为可执行命令[args...]存入args支持--env支持--env-file存储到env_file字段拒绝--header报错--header can only be used with http or sse transport支持且推荐-- command [args...]写法以保证无歧义解析。http / streamable-http / ssecommand-or-url必须是合法 URLurl.ParseRequestURI校验要求 scheme 与 host 均非空否则报invalid MCP URL额外的命令参数被拒绝拒绝--env与--env-file支持--header存储到headers字段http与streamable-http都使用 streamable HTTP 请求-响应模式sse同样基于 streamable HTTP 传输但额外启用独立的 SSE 监听用于接收服务端主动推送的通知。覆盖确认与本地路径校验当name已存在时CLI 会询问确认MCP server x already exists. Overwrite? [y/N]:见 helpers.go 的confirmOverwrite回答y/yes才继续用--force可跳过提示当命令看起来是本地路径如./server.py、/opt/mcp/server时CLI 会检查文件是否存在在非 Windows 平台还会检查是否具有可执行权限见 helpers.go 的validateLocalCommandPath通过os.Stat与Mode()0o111判断当目标看起来像https://...但传输类型仍是默认的stdio时CLI 会给出明确报错target ... looks like a remote MCP URL, but transport is stdio. Use --transport http or --transport sse判定逻辑是looksLikeRemoteURL识别http/httpsscheme 且 host 非空的输入。picoclaw mcp removepicoclaw mcp remove name从tools.mcp.servers中删除指定条目。若被删除的是最后一个服务器则同时将tools.mcp.enabled置为falsemap 清空为 nil 后触发。条目不存在时返回明确错误MCP server x not found。picoclaw mcp listpicoclaw mcp list picoclaw mcp list --status宽终端下输出为带样式的方框与mcp show风格一致窄终端或 stdout 非 TTY 时退化为纯 ASCII 表格未配置任何服务器时输出No MCP servers configured.。输出字段字段含义Nametools.mcp.servers中的服务器键名Type生效的传输类型stdio、http或sse由config.EffectiveMCPTransportType推断见 helpers.go 的inferTransportTypeCommand/Targetstdio 服务器的完整命令行或远程服务器的 URLrenderServerTarget拼接command与argsStatus默认显示enabled/disabled带--status时为ok (N tools)或errorDeferred显式覆盖为true时显示deferred为false时显示eager未设置时不显示要点不带--status只输出配置态不做任何网络连接适合快速盘点带--status时会对每个已启用服务器做实时探测serverProbe每个探测有独立超时--timeout默认 5 秒想看某服务器暴露的完整工具列表用picoclaw mcp show name。picoclaw mcp showpicoclaw mcp show name picoclaw mcp show name --timeout 15s连接指定服务器并打印服务器元信息名称、传输类型、目标、启用状态、deferred 覆盖、环境变量名只列键名不泄值、env 文件路径、header 名该服务器暴露的每一个工具名称、描述、参数名称、类型、required/optional、描述。参数由extractParameters见 show.go从工具的 JSON Schema 中提取读取properties并按名称排序required数组中的参数标记为必填。宽终端下的示例输出╭──────────────────────────────────────────────────────────╮ │ ⬡ filesystem │ │ │ │ Type stdio │ │ Target npx -y modelcontextprotocol/server-fs /tmp │ │ Enabled yes │ │ Deferred no │ │ │ │ Tools (3) │ │ │ │ read_file [1/3] │ │ Read the complete contents of a file from the disk │ │ │ │ path string required │ │ Path to the file to read │ │ ──────────────────────────────────────────────────────── │ │ ... │ ╰──────────────────────────────────────────────────────────╯FlagFlag默认值含义--timeout10s连接超时时间注意两点服务器在配置中被禁用enabled: false时mcp show只打印元信息跳过工具发现mcp show总是实时连接来拉取工具列表如果只需要可达性检查用更轻量的mcp test。picoclaw mcp testpicoclaw mcp test name对单个已配置条目做直接连接测试成功后打印发现到的工具数量✓ MCP server x reachable (N tools).默认超时 5 秒。它适合以下场景启动 gateway 之前先验证新添加的服务器是否可用只调试某一个服务器而不想探测整个列表条目当前在配置中被禁用但想校验其定义本身是否有效探测时会临时以enabled: true加载见 helpers.go 的defaultServerProbe。picoclaw mcp editpicoclaw mcp edit用$EDITOR打开配置文件。用于配置那些picoclaw mcp add没有直接暴露为 flag 的 MCP 字段例如tools.mcp.discovery、max_inline_text_chars等。实现细节见 edit.go读取$EDITOR未设置时直接报错$EDITOR is not set会用shlex.Split解析编辑器命令支持带参数的编辑器命令并先执行一次saveValidatedConfig规范化配置再拉起编辑器进程。stdin/stdout/stderr 均透传给编辑器保证交互式编辑体验。推荐工作流常规场景用picoclaw mcp add添加服务器希望工具默认隐藏时加--deferred用picoclaw mcp show name验证连通性并检查暴露的工具用picoclaw mcp list --status一览所有服务器的健康状态正常启动 PicoClaw由宿主机加载配置的 MCP 服务器。进阶场景先用picoclaw mcp add添加基础条目运行picoclaw mcp edit补齐 CLI flag 未覆盖的字段用picoclaw mcp show name确认最终配置与工具列表。相关文档Tools ConfigurationMCP 配置结构、传输方式、发现机制与完整示例README项目总览。【免费下载链接】picoclawTiny, Fast, and Deployable anywhere — automate the mundane, unleash your creativity项目地址: https://gitcode.com/gh_mirrors/pi/picoclaw创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考