OpenClaw 通过 MCPorter 接入 MCP 服务实践指南# OpenClaw 通过 MCPorter 接入

OpenClaw 通过 MCPorter 接入 MCP 服务实践指南

本文说明：MCP 是什么、为何 OpenClaw 不能像在 Cursor 里那样直接挂 MCP、如何用 MCPorter 作为桥梁，以及如何用 Skill 让 OpenClaw（俗称「小龙虾」）学会通过命令行调用各类 MCP 服务。

约定：openclaw.json / MCPorter 行为以你本机安装的版本为准；文中 ShipLab、RepoLens 等为虚构服务名，仅演示配置形态。

1. MCP 是什么（Model Context Protocol）— 概念详解

1.1 定义与定位

MCP（Model Context Protocol，模型上下文协议） 是一套开放标准，用来在 AI 应用（宿主 / Host） 与 外部能力（MCP Server） 之间，用统一方式交换「上下文」和「可执行能力」。常被比喻为 「AI 的 USB-C」：不同厂商的编辑器、Agent、CLI 只要实现 MCP 客户端，就能按同一套规范接上各种 MCP 服务，而不必为每个业务单独写一套私有插件协议。

规范与生态：由 Anthropic 发起并开源，规范与实现可参考 modelcontextprotocol（含 specification、官方 SDK 等）。
要解决什么问题：大模型本身不知道你公司的交付系统、代码仓库、知识库、浏览器……传统做法是每家产品自己接 API、写适配层。MCP 把「发现能力 → 描述参数 → 调用 → 拿回结果」这条链路标准化，降低重复造轮子。

1.2 核心角色（谁连谁）

┌──────────────┐      ┌──────────────┐      ┌──────────────┐
│ Host 宿主     │ ←→  │ MCP Client   │ ←→  │ MCP Server   │
│ Cursor 等     │      │ 内置或独立    │      │ 本地/远端服务 │
└──────────────┘      └──────────────┘      └──────────────┘

（独立用 MCPorter 调 MCP 时，可把 MCPorter 进程理解为承担 Client 角色、由你在终端或 exec 里启动。）

Host：承载对话界面的程序（如 Cursor、Claude Desktop）。负责把「模型想调工具」的意图交给 Client。
MCP Client：按协议与 Server 建连、发请求、收响应；可以嵌在 Host 里，也可以是 MCPorter 这种独立 CLI/运行时。
MCP Server：真正提供能力的一方：查文档、查发布单、读代码、搜知识库等。一个 Server 可暴露多个工具（Tools），有的还暴露 资源（Resources）、提示模板（Prompts）。

1.3 Server 通常提供什么能力

能力类型	含义（简化）	模型侧体验
Tools（工具）	可调用的函数：有名字、JSON Schema 描述的入参/出参	模型在上下文中看到「有哪些工具、各参数什么意思」，决定何时 `call_tool`
Resources（资源）	可读的数据源，常带 URI（如 `file://`、`custom://`）	模型或客户端按需拉取内容进上下文
Prompts（提示）	预置的多轮/结构化提示模板	客户端可选用，减少手写 system prompt

日常对话里大家说的「接 MCP」，多数指的是 Tools：例如 shiplab.list_projects、repolens.search_repo，本质是 一次带结构化参数的远程过程调用，结果再塞回对话继续推理。

1.4 传输方式（怎么连上 Server）

MCP 不限定只有一种网络形态，常见有：

传输	典型场景	配置形态（概念）
stdio	Server 是本地子进程，通过标准输入输出传 JSON 消息	`command` + `args`，如 `npx -y 某-mcp@latest`
HTTP / SSE	Server 在远端 URL，用 HTTP 或 Server-Sent Events 流式通信	`url` / `baseUrl`（如 `https://mcp.example.com/xxx/mcp`）
Streamable HTTP 等	规范演进中的新传输	依客户端与服务端版本而定

鉴权常见：Header（Bearer Token）、OAuth 浏览器登录（由客户端拉起浏览器，token 缓存在本机）。

1.5 一次「调工具」在协议层面大致做什么（直觉版）

初始化：Client 与 Server 握手，协商协议版本。
列举能力：Client 请求 tools/list（及 resources 等），Server 返回工具名、描述、JSON Schema。
调用：模型（或上层逻辑）选中某工具名 + 参数对象，Client 发 tools/call，Server 执行业务逻辑并返回 文本 / 结构化内容 / 多模态块 等。
错误：网络失败、鉴权失败、业务 4xx/5xx 等由 Client 转成错误信息再给上层。

你使用 MCPorter 时，mcporter list 相当于帮你把第 2 步的结果美化成可读签名；mcporter call 相当于替你走第 3 步。

1.6 MCP 和普通 REST API 有什么不一样（面向 AI 场景）

对比点	普通 HTTP API	MCP
发现能力	常靠人工读文档	标准流程列出工具 + Schema，便于客户端和模型消费
参数约定	各公司各异	工具入参多用 JSON Schema，利于校验与 Few-shot
调用形态	随意 path/body	统一语义（tools/call 等），多宿主可复用同一 Server 实现
目标用户	主要是工程师调接口	同时为「宿主程序」和「模型推理」设计

MCP 不是替代你司内部所有 HTTP 接口；而是：在「让 AI 安全、可发现地调用外部能力」这一层提供共同语言。

1.7 安全与信任

MCP Server 能做什么，取决于 Server 实现 与 运行环境权限（本地进程继承本机权限；远端服务则受 token 与网络边界限制）。
只应连接 你信任的 Server；恶意或过度授权的 Server 可能造成数据外泄或误操作。
企业内网 MCP（如交付平台、代码洞察类服务）通常还有 OAuth / 企业 SSO 等身份体系，与公网 Demo 不同。

1.8 和本文其他概念的关系（承上启下）

Cursor：内置 MCP Client，在设置里配好 mcpServers 后，对话里的模型可直接走 MCP。
OpenClaw：若配置 schema 不允许根级 mcpServers，则没有「一等公民」的 MCP 配置位；此时用 MCPorter 作为独立 Client，再通过 exec 让 Agent 执行 npx mcporter call ...，等价于「外挂了一个 MCP 客户端」。
即时通讯频道插件：若 OpenClaw 通过 WebSocket 连自建消息中继 接入某 IM（如企业机器人），其协议与 Model Context Protocol 的 Tools 不是同一条线，勿与 MCP 混为一谈。

2. 背景：三种东西别混了

概念	是什么	在 OpenClaw 里
MCP（Model Context Protocol）	见 §1：给 AI 暴露工具/资源等的开放协议，常见 HTTP/SSE、stdio	当前版本 `openclaw.json` 根级不支持 `mcpServers`，直接写会报 Unrecognized key
MCPorter	命令行 + TypeScript 运行时，可发现/调用已配置的 MCP，并合并 Cursor、Claude 等配置	通过 `npx mcporter call 服务名.工具名 ...` 调 MCP
IM 频道类插件	OpenClaw 的频道扩展（示例键名 `channels.<你的中继插件>`），走 WebSocket 连消息中继服务	与「用 MCPorter 调 ShipLab/RepoLens 等 MCP」不是同一条路，配置在 `channels` 里

结论：OpenClaw 本体不内置「像 Cursor 那样的 MCP 客户端」时，用 MCPorter + exec + Skill，是最实用的接入方式。

3. MCPorter 教程（从零到熟练）

MCPorter 是 TypeScript 运行时 + CLI，用来发现、调用 MCP 服务，支持 HTTP/SSE、stdio、OAuth 等。官方仓库：steipete/mcporter，npm 包名：mcporter。

3.1 安装方式

方式	命令
临时用（推荐先试）	`npx mcporter list`、`npx mcporter call ...`
全局安装	`npm install -g mcporter` 或 `pnpm add -g mcporter`
Homebrew（macOS）	`brew tap steipete/tap && brew install steipete/tap/mcporter`

注意：全局安装若报 EPERM，执行 sudo chown -R $(whoami) ~/.npm。npx 若遇缓存/内网 registry 403，可：npm install ... --registry https://registry.npmjs.org --cache /tmp/mcporter-npm-cache。

安装后终端里可直接打 mcporter；未全局安装则一律写 npx mcporter。

3.2 配置文件从哪读

MCPorter 每次运行只选一个主配置，查找顺序大致为：

命令行 --config <路径>
环境变量 MCPORTER_CONFIG
当前项目下的 config/mcporter.json（或 .jsonc）
用户目录 ~/.mcporter/mcporter.json 或 ~/.mcporter/mcporter.jsonc

支持 JSONC（注释、尾逗号）。可把常用 MCP 全写在 ~/.mcporter/mcporter.json，与 Cursor 侧 MCP 配置 手动对齐（常见路径为 ~/.cursor/mcp.json 或项目目录下 .cursor/mcp.json，以 Cursor 版本与本机为准）。Cursor 里 HTTP 类多用 url，MCPorter 里对应 baseUrl。

可选在配置里加 imports，自动合并 Cursor、Claude Desktop 等（具体键名以你本机 mcporter 版本文档为准），例如：

{
  "mcpServers": { ... },
  "imports": ["cursor", "claude-desktop", "vscode"]
}

3.3 在配置里描述一个 MCP 服务

HTTP/SSE 类（与 Cursor url 对应）：

"mcpServers": {
  "服务别名": {
    "description": "说明",
    "baseUrl": "https://example.com/mcp",
    "headers": { "Authorization": "Bearer $env:YOUR_TOKEN" }
  }
}

需要 OAuth："auth": "oauth"，然后在本机终端执行 npx mcporter auth 服务别名（拉起浏览器登录）。若全局 npm 需要 root 写权限，再改用 sudo npx mcporter auth …。
环境变量占位：${VAR}、$env:VAR 等（见官方 docs/config.md）。

Stdio 类（本地进程）：

"某服务": {
  "command": "npx",
  "args": ["-y", "某-mcp包@latest"],
  "env": { "KEY": "value" }
}

3.4 核心命令：`list` 与 `call`

# 列出已配置的所有服务概况（可加 --json）
npx mcporter list

# 列出某个服务下的工具（会打印类似 TypeScript 的函数签名）
npx mcporter list shiplab
npx mcporter list shiplab --all-parameters
npx mcporter list shiplab --schema

# 调用工具：两种常见写法

# A. 冒号 / 等号 传参（适合简单参数）
npx mcporter call shiplab.list_my_projects
npx mcporter call linear.create_comment issueId:ENG-123 body:'内容'

# B. 函数式（复杂参数、字符串 ID 更稳，内网类 MCP 常需要）
npx mcporter call 'shiplab.get_release_detail(releaseId: "10001")'
npx mcporter call 'shiplab.trigger_deploy(releaseId: 12345, stage: "staging")'

可省略动词：mcporter shiplab.xxx 会推断为 call。
超时：环境变量 MCPORTER_LIST_TIMEOUT、MCPORTER_CALL_TIMEOUT。
失败时可用 --output json 拿结构化错误便于脚本处理。

3.5 不写配置文件，临时指定地址

npx mcporter list --http-url https://mcp.example.com/mcp --name mysvc
npx mcporter call --http-url https://mcp.example.com/mcp --name mysvc 工具名 参数...

需要持久化：加 --persist config/mcporter.local.json 或 mcporter config add ...。

3.6 `mcporter config` 子命令（少手改 JSON）

npx mcporter config list
npx mcporter config get <服务名>
npx mcporter config add ...
npx mcporter config remove ...
npx mcporter config import cursor --copy   # 把 Cursor 里的项拷进本地 mcporter.json

3.7 守护进程与长连接

部分 stdio MCP（如 chrome-devtools）会由 daemon 保活。可查：

mcporter daemon status
mcporter daemon stop

配置里可对某服务设 "lifecycle": "keep-alive" 等（见官方 README）。

3.8 代码里调用（可选）

import { callOnce, createRuntime, createServerProxy } from "mcporter";
// callOnce：单次调用自动发现、关连接
// createRuntime：连接池、多次 callTool

3.9 与 OpenClaw 插件 `openclaw plugins install mcporter` 的区别

MCPorter 的 npm 包通常没有 openclaw.extensions，不是 OpenClaw 的频道插件；应用 npm install -g mcporter 或 npx mcporter，不要用 openclaw plugins install mcporter 当「装 MCP 进 OpenClaw」。

3.10 延伸阅读

官方 CLI 参考：docs/cli-reference.md
调用语法：docs/call-syntax.md、docs/tool-calling.md
临时连接：docs/adhoc.md
配置：docs/config.md

4. 在 MCPorter 里登记 MCP 服务

编辑 ~/.mcporter/mcporter.json（JSON/JSONC），在 mcpServers 下增加条目；与 Cursor MCP 配置里的 url 指向同一服务端点时，在 MCPorter 侧用 baseUrl 填写等价地址。

示例（虚构内网多服务，仅演示形态）：

{
  "mcpServers": {
    "shiplab": {
      "description": "ShipLab 交付/发布类 MCP（虚构名）",
      "baseUrl": "https://mcp.internal.example.org/shiplab/mcp",
      "auth": "oauth",
      "headers": {}
    },
    "repolens": {
      "description": "RepoLens 代码洞察 MCP（虚构名）",
      "baseUrl": "https://mcp.internal.example.org/repolens/mcp",
      "auth": "oauth",
      "headers": {}
    },
    "teamhub": {
      "description": "TeamHub 协作 MCP（虚构名）",
      "baseUrl": "https://mcp.internal.example.org/teamhub/mcp",
      "auth": "oauth",
      "headers": {}
    },
    "wikistream": {
      "description": "WikiStream 知识库 MCP（虚构名）",
      "baseUrl": "https://mcp.internal.example.org/wikistream/mcp",
      "auth": "oauth",
      "headers": {}
    }
  }
}

需要浏览器 OAuth 的服务：加 "auth": "oauth"，在本机终端执行一次：
npx mcporter auth <服务名>（或环境需要时用 sudo npx …；需本机交互，无法在 IDE 里完全代劳）。
若某服务报 405/鉴权失败，再对照 Cursor 里是否已登录、以及是否必须走 OAuth。

5. 为什么 Cursor 能连、OpenClaw「同款命令」有时不行

Cursor：内置 MCP 客户端，OAuth 与会话 token 由 Cursor 进程管理（与终端里的 ~/.mcporter 缓存不一定相同）。
OpenClaw：通过 exec 起子进程执行 npx mcporter ...，用的是 本机 ~/.mcporter 的 token 与环境；若子进程环境或缓存与终端不一致，可能出现 Internal Server Error，而 Cursor 侧正常。
缓解：在本机终端用同一条 npx mcporter call ... 验证；保证已 mcporter auth；OpenClaw 的 exec 与日常终端同一用户、能读 ~/.mcporter。

6. 教会「小龙虾」：用 OpenClaw Skill

OpenClaw 会按 Skill 的 description 匹配用户意图，加载 SKILL.md 里的说明。思路是：

在 ~/.openclaw/workspace/skills/<名称>/SKILL.md 写明：
- 没有内置某某 MCP；
- 必须用 exec，program 为 /bin/bash，args 为 ["-c", "npx mcporter call ..."]；
- 禁止只回复「你可以执行某命令」而不真正调 exec。
对 ShipLab 类（工具多、参数刁钻）的服务，在 Skill 里写清：
- 意图 → 工具名 → 已验证命令；
- 资源标识使用 namespace/project（或你司约定的 group/project），不要只写短名；
- 重新部署/发版 往往对应类似 trigger_deploy 的工具，环境参数需按服务端约定（如 dev / staging / prod）；某些应用类型可能限制可用环境；
- 详情类接口尽量用 函数式并把 ID 写成字符串，避免纯数字参数触发服务端 500。

Skill 目录示例（命名可随你司服务调整）：

skills/shiplab-mcporter/SKILL.md — 交付/迭代/部署类
skills/repolens-mcporter/SKILL.md — 代码类，先 list repolens 再 call
skills/teamhub-mcporter/SKILL.md — 协作类
skills/wikistream-mcporter/SKILL.md — 知识库类

新增 MCP 时：Cursor 里加好 mcp.json → 同步写入 ~/.mcporter/mcporter.json → 复制一份 Skill 模板改服务名与 description。

7. 虚构「ShipLab」类 MCP 命令行要点（易踩坑）

以下工具名为教学用虚构名，实际以 npx mcporter list shiplab 为准。

场景	建议命令形态
我的项目列表	`npx mcporter call shiplab.list_my_projects`
项目详情 / 发布单列表	资源 ID 用 `"namespace/project"`，函数式调用
发布单详情	`npx mcporter call 'shiplab.get_release_detail(releaseId: "发布单ID")'`
触发部署	`npx mcporter call 'shiplab.trigger_deploy(releaseId: 数字, stage: "staging")'`（示例：预发环境）
任务结果	`npx mcporter call 'shiplab.get_job_result(jobId: "任务ID字符串")'`（ID 形态以 `list --all-parameters` 为准）

不确定时：npx mcporter list shiplab --all-parameters。

8. 与「对话模型 API」配置的关系

大模型 Chat API（某云厂商 OpenAI 兼容 端点，示例：https://api.example-vendor.com/v1）配置在 openclaw.json → models.providers，与 MCP / MCPorter 无关。
MCP 工具走 MCPorter → 各 MCP 的 baseUrl；对话模型走你配置的 agents.defaults.model.primary（例如 my-vendor/deepseek-v3.2）。

9. 排错清单

openclaw.json 里写 mcpServers 报错 → 当前 schema 不支持，改用 MCPorter + Skill。
npx mcporter 装不上 / 403 → 换 registry、修 ~/.npm 权限，或 --cache /tmp/xxx。
OAuth 服务连不上 → npx mcporter auth <服务名>（必要时 sudo npx …），本机浏览器完成登录。
某 MCP 返回 500 或 {} → 改函数式、字符串 ID、namespace/project 类复合标识。
IM 频道断连 → 查 channels.* 里中继地址、accessToken、网络/VPN；与 MCPorter 无关。

10. 小结

MCP 是开放协议（§1）：Host / Client / Server，Tools/Resources/Prompts，stdio 与 HTTP/SSE 等传输；理解后再看 OpenClaw 与 Cursor 的差异会更清晰。
OpenClaw 不（一定）内置 MCP 配置项时，MCPorter = 统一入口：配置在 ~/.mcporter/mcporter.json，调用用 npx mcporter call。
教会小龙虾 = 写好 Skill：说明必须用 exec、给出已验证命令与踩坑说明。
Cursor 与 OpenClaw 共用同一套 MCP 地址时，两边配置对齐，再分别处理 OAuth 与 exec 环境即可。
插图占位与生图提示词见 附录 A。

文档根据通用实践整理，文中产品名与域名为虚构示例；随 OpenClaw / MCPorter 版本升级请以官方文档为准。

OpenClaw 通过 MCPorter 接入 MCP 服务实践指南