McPorter 实战：一键管理 OpenClaw 的 MCP 服务器

McPorter 实战：一键管理 OpenClaw 的 MCP 服务器

🚀 MCP 服务器配好了一堆，却只能在 Agent 聊天里用？McPorter 让你在终端里直接列出、调用、调试任何 MCP 服务器——还能生成 TypeScript 客户端代码

📑 文章目录

1. 痛点：MCP 服务器配好了，然后呢？

如果你跟着我之前的文章在 OpenClaw 里配好了几个 MCP 服务器，你可能会碰到这些问题：

配好 MCP 服务器后的常见困扰：

1. 服务器到底有哪些工具？ ← 翻文档 or 猜
2. 工具的参数格式是什么？ ← 每个 Server 都不一样
3. 想快速测试一个工具调用？ ← 只能通过 Agent 聊天触发
4. OAuth 认证过期了怎么办？ ← 手动重新走流程
5. 在 CI/CD 里想调 MCP 工具？ ← 没有好办法
6. 已经在 Cursor/Claude 配了 MCP，不想重复配置 ← 配置散落各处
7. 想给别人共享一个 MCP 工具的 CLI？ ← 没法脱离 Agent 使用

McPorter 就是为了解决这些问题而生的。

2. McPorter 是什么：MCP 的统一 CLI 运行时

一句话定义

McPorter 是一个 MCP 服务器的 CLI 运行时和 TypeScript SDK，让你可以在终端或代码中直接列出、调用、认证和管理 MCP 服务器——无需通过 AI Agent 中转。

注意：McPorter ≠ 包管理器

很多人第一反应是"McPorter 是 MCP 的 apt-get"——这是错的。McPorter 不负责安装 MCP 服务器包，也不是注册表/商店。它的核心能力是：

零配置自动发现

McPorter 最强大的特性之一是零配置发现——它会自动合并以下来源的 MCP 服务器配置：

McPorter 配置合并优先级（高 → 低）：

1. 命令行 ad-hoc 参数（–http-url / –stdio）
2. 项目级配置：./config/mcporter.json
3. 用户级配置：~/.mcporter/mcporter.json
4. 自动导入：
├── Cursor: ~/.cursor/mcp.json
├── Claude: ~/.claude.json / .mcp.json
├── Codex: codex 配置文件
├── Windsurf: windsurf 配置文件
├── VS Code: vscode 配置文件
└── OpenCode: opencode 配置文件

💡 这意味着如果你已经在 Cursor 或 Claude Desktop 里配过 MCP 服务器，McPorter 直接就能用——不需要重新配置！

3. McPorter vs 手动配置 vs OpenClaw Skills：三者关系

三者对比

它们的关系

┌─────────────────────────────────────────────────┐
│ 你的工作环境 │
│ │
│ OpenClaw Agent │
│ ├── Skills (来自 ClawHub) │
│ ├── MCP Servers (openclaw.json 配置) │
│ └── 内置工具 │
│ │
│ Cursor / Claude Desktop / VS Code │
│ └── MCP Servers (各自的 mcp.json 配置) │
│ │
│ McPorter ← 统一层 │
│ ├── 自动发现上述所有 MCP 配置 │
│ ├── 提供 CLI 直接调用任何工具 │
│ ├── 管理 OAuth 认证 │
│ └── 生成 TypeScript 客户端 / 独立 CLI │
└─────────────────────────────────────────────────┘

💡 简单记法：OpenClaw/Cursor/Claude 各自管自己的 MCP 配置，McPorter 是横跨它们之上的统一调用层。你不用它也能用 MCP，但有了它，调试和开发效率大幅提升。

4. 安装 McPorter

4.1 通过 npm 安装（推荐）

# 全局安装
npm install -g mcporter

# 验证安装
mcporter –version
# mcporter 0.7.3

4.2 通过 Homebrew 安装（macOS）

brew install pdxfinder/tap/mcporter

4.3 免安装使用（npx）

# 不安装，直接用
npx mcporter list

5. 核心命令速查：list、call、config、auth

5.1 🔍 list — 列出服务器和工具

# 列出所有已配置的 MCP 服务器
npx mcporter list
# 输出示例：
# brave-search – Brave Search MCP (2 tools, 0.3s) [source: ~/.cursor/mcp.json]
# postgres – PostgreSQL MCP (3 tools, 0.5s) [source: ./config/mcporter.json]
# filesystem – Filesystem MCP (5 tools, 0.2s) [source: ~/.claude.json]
# ✔ Listed 3 servers (3 healthy)

# 查看某个 Server 的工具签名（TypeScript 风格）
npx mcporter list brave-search
# brave-search – Brave Search MCP; web and local search
# 2 tools · 312ms · stdio
#
# /**
# * Search the web using Brave Search
# * @param query The search query string
# * @param count Number of results to return
# */
# function brave_web_search(query: string, count?: number);
#
# /**
# * Search for local businesses and places
# * @param query Local search query
# */
# function brave_local_search(query: string);

# 显示完整 JSON Schema
npx mcporter list brave-search –schema

5.2 📞 call — 直接调用 MCP 工具

# 基本调用语法：mcporter call <server.tool> key=value
npx mcporter call brave-search.brave_web_search query="OpenClaw MCP best practices"

# 函数风格调用
npx mcporter call "brave-search.brave_web_search(query: \\"OpenClaw 2026\\")"

# JSON 参数方式
npx mcporter call brave-search.brave_web_search –args '{"query": "MCP tutorial", "count": 5}'

# 调用本地 stdio 服务器（无需预先配置）
npx mcporter call –stdio "npx -y @modelcontextprotocol/server-filesystem /tmp" list_directory path=/tmp

# 调用远程 HTTP MCP 服务器
npx mcporter call https://mcp.example.com/mcp fetch url=https://example.com

# 查看响应的原始日志
npx mcporter call postgres.pg_query query="SELECT 1" –tail-log

5.3 ⚙️ config — 管理配置

# 列出当前配置中的所有服务器
npx mcporter config list

# 添加一个新的 MCP 服务器配置
npx mcporter config add brave-search –stdio "npx -y @modelcontextprotocol/server-brave-search" \\
–env BRAVE_API_KEY=BSAxxxxxxxxx

# 从 Cursor 导入配置
npx mcporter config import cursor

# 从 Claude Desktop 导入
npx mcporter config import claude-code

# 删除一个配置
npx mcporter config remove brave-search

# 查看某个服务器的配置来源
npx mcporter config get brave-search

配置文件格式（config/mcporter.json）：

// config/mcporter.json — 支持 JSONC（注释 + 尾逗号）
{
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "${BRAVE_API_KEY}" // 支持 ${ENV} 占位符
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "${POSTGRES_CONNECTION_STRING}"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/workspace"]
}
}

5.4 🔑 auth — OAuth 认证

# 对需要 OAuth 的服务器进行认证（如 Linear、Vercel）
npx mcporter auth linear
# → 自动打开浏览器完成 OAuth 流程
# → Token 缓存到 ~/.mcporter/<server>/

# 重置认证
npx mcporter auth linear –reset

# 对远程 HTTP 服务器认证
npx mcporter auth https://mcp.linear.app/mcp

5.5 🤖 daemon — 后台服务

# 启动后台 daemon（持续运行 MCP 服务器进程）
npx mcporter daemon start

# 查看 daemon 状态
npx mcporter daemon status

# 重启 / 停止
npx mcporter daemon restart
npx mcporter daemon stop

6. 实战一：列出所有可用的 MCP 服务器和工具

假设你已经在 Cursor 里配了几个 MCP 服务器，又在 OpenClaw 的 openclaw.json 里配了几个。McPorter 能一次性发现它们全部：

npx mcporter list
# 输出：
# brave-search – Brave Search (2 tools, 312ms) [source: ~/.cursor/mcp.json]
# linear – Hosted Linear MCP (23 tools, 1654ms) [source: ~/.cursor/mcp.json]
# filesystem – Filesystem MCP (5 tools, 89ms) [source: ./config/mcporter.json]
# vercel – Vercel MCP (requires OAuth) [source: ~/.cursor/mcp.json]
# ✔ Listed 4 servers (3 healthy, 1 requires auth)

看到 vercel 需要 OAuth？一条命令搞定：

npx mcporter auth vercel
# → 浏览器打开，完成 Vercel OAuth
# ✅ Token cached to ~/.mcporter/vercel/

再次 list：

npx mcporter list vercel
# vercel – Vercel MCP (requires OAuth)
# 15 tools · 890ms · HTTP https://mcp.vercel.com/mcp
#
# function search_documentation(topic: string);
# function list_projects(limit?: number);
# …

7. 实战二：从终端直接调用 MCP 工具

这是 McPorter 最实用的场景——不需要打开 Agent 聊天，直接在终端测试和调用 MCP 工具。

7.1 调用 Brave Search

npx mcporter call brave-search.brave_web_search query="McPorter MCP CLI"
# 返回搜索结果的 JSON

# 拼手动 typo？McPorter 会自动纠正
npx mcporter call brave-search.brave_web_serch query="test"
# ⚠ Did you mean brave_web_search? (edit distance: 1)
# → 自动重试正确的工具名

7.2 调用 PostgreSQL

npx mcporter call postgres.query query="SELECT count(*) FROM users"

7.3 调用 Ad-hoc 服务器（无需预先配置）

# 直接指定一个 stdio 命令
npx mcporter call –stdio "npx -y @modelcontextprotocol/server-filesystem /tmp" \\
list_directory path=/tmp

# 直接指定一个 HTTP URL
npx mcporter call https://mcp.context7.com/mcp resolve-library-id query=react

7.4 在脚本和 CI/CD 中使用

# JSON 输出，方便管道处理
npx mcporter call brave-search.brave_web_search query="test" –output json | jq '.content[0].text'

8. 实战三：添加和管理 MCP 服务器配置

8.1 添加 Brave Search

# 1. 添加到 mcporter 配置（不是 openclaw.json）
npx mcporter config add brave-search \\
–stdio "npx -y @modelcontextprotocol/server-brave-search" \\
–env BRAVE_API_KEY=BSAxxxxxxxxxxxxxxxxxx

# 2. 验证
npx mcporter list brave-search

8.2 添加 PostgreSQL

npx mcporter config add postgres \\
–stdio "npx -y @modelcontextprotocol/server-postgres" \\
–env POSTGRES_CONNECTION_STRING="postgresql://readonly:xxx@localhost:5432/mydb"

npx mcporter call postgres.list_tables

8.3 添加 Filesystem

npx mcporter config add filesystem \\
–stdio "npx -y @modelcontextprotocol/server-filesystem /home/user/workspace"

🚨 目录限制是安全底线。Filesystem MCP 只能访问你在 args 中指定的目录。绝对不要把 / 或 ~ 整个给它。

8.4 从现有工具导入配置

# 如果你已经在 Cursor 里配好了 MCP 服务器
npx mcporter config import cursor
# ✔ Imported 5 servers from ~/.cursor/mcp.json

# 从 Claude Desktop 导入
npx mcporter config import claude-code

9. 实战四：OAuth 认证与远程 MCP 服务器

越来越多的 MCP 服务器使用 Streamable HTTP + OAuth 模式，不再要求本地安装 npm 包。McPorter 对此有一流支持：

# 认证 Linear（托管 MCP 服务器）
npx mcporter auth https://mcp.linear.app/mcp
# → 自动检测需要 OAuth
# → 在 127.0.0.1 启动临时回调服务器
# → 打开浏览器完成授权
# → Token 持久化到 ~/.mcporter/linear/

# 然后就可以直接调用
npx mcporter call linear.searchIssues team=ENG status=InProgress

# Token 过期？重新认证
npx mcporter auth linear –reset

10. 进阶：生成 TypeScript 客户端和独立 CLI

10.1 生成独立 CLI

想把某个 MCP 服务器包装成一个独立的命令行工具？

# 为 Context7 生成独立 CLI
npx mcporter generate-cli \\
–server '{"name":"context7","command":"https://mcp.context7.com/mcp"}' \\
–output dist/context7.ts \\
–runtime bun \\
–compile

# 生成的 CLI 可以直接运行
chmod +x dist/context7
./dist/context7 resolve-library-id react

# 只包含部分工具
npx mcporter generate-cli –server linear –include-tools searchIssues,createIssue

# 试运行（看看会生成什么，但不实际执行）
npx mcporter generate-cli –from linear –dry-run

10.2 生成 TypeScript 类型定义

# 生成 .d.ts 类型文件
npx mcporter emit-ts linear –mode types –out linear.d.ts

# 生成可用的客户端代码
npx mcporter emit-ts linear –mode client –out linear-client.ts

10.3 在 TypeScript 代码中使用

import { createRuntime, createServerProxy } from "mcporter";

const runtime = await createRuntime({
servers: [
{
name: "brave-search",
command: {
kind: "stdio",
command: "npx",
args: ["-y", "@modelcontextprotocol/server-brave-search"],
env: { BRAVE_API_KEY: process.env.BRAVE_API_KEY! }
}
}
]
});

// 工具调用变成 TypeScript 方法
const proxy = createServerProxy(runtime, "brave-search");
const result = await proxy.braveWebSearch({ query: "McPorter tutorial" });
console.log(result.text());

11. McPorter + OpenClaw：联合使用最佳实践

OpenClaw 配置 MCP 的方式

OpenClaw 使用自己的 ~/.openclaw/openclaw.json（JSON5 格式）来配置 MCP 服务器，写法如下：

// ~/.openclaw/openclaw.json
{
// OpenClaw 自动监控此文件并热加载，大部分改动不需要重启 Gateway
"mcpServers": {
"brave-search": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-brave-search"],
"env": {
"BRAVE_API_KEY": "${BRAVE_API_KEY}"
}
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres"],
"env": {
"POSTGRES_CONNECTION_STRING": "${POSTGRES_CONNECTION_STRING}"
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/workspace"]
}
}
}

McPorter 在 OpenClaw 工作流中的角色

┌──────────────────────────────────────────────────────────┐
│ 你的日常工作流 │
│ │
│ 📱 通过聊天使用 MCP 工具 → OpenClaw Agent │
│ "帮我查一下数据库里有多少用户" │
│ Agent 自动调用 postgres MCP 的 query 工具 │
│ │
│ 💻 从终端调试/测试 MCP 工具 → McPorter │
│ npx mcporter call postgres.query query="SELECT 1" │
│ 快速验证工具是否正常，无需等 Agent │
│ │
│ 🔧 开发自动化脚本 → McPorter TypeScript SDK │
│ import { callOnce } from "mcporter"; │
│ 在 CI/CD 或脚本中直接调用 MCP 工具 │
│ │
│ 🔑 管理 OAuth 认证 → mcporter auth │
│ npx mcporter auth linear │
│ 统一处理所有 MCP 服务器的 OAuth 流程 │
└──────────────────────────────────────────────────────────┘

实用组合技

# 1. 先用 McPorter 在终端快速测试一个新的 MCP 服务器
npx mcporter call –stdio "npx -y @modelcontextprotocol/server-brave-search" \\
brave_web_search query="test"
# ✅ 确认工作正常

# 2. 满意后，手动添加到 OpenClaw 配置
# 编辑 ~/.openclaw/openclaw.json，添加 mcpServers 配置
# OpenClaw Gateway 会自动热加载

# 3. 同时添加到 McPorter 配置（方便以后终端调试）
npx mcporter config add brave-search \\
–stdio "npx -y @modelcontextprotocol/server-brave-search" \\
–env BRAVE_API_KEY=$BRAVE_API_KEY

McPorter 常用命令速查卡

# === 发现 ===
mcporter list # 列出所有已配置的 MCP 服务器
mcporter list <server> # 查看某个服务器的工具签名
mcporter list <server> –schema # 显示完整 JSON Schema
mcporter list <server> –all-parameters # 显示所有参数（含可选）

# === 调用 ===
mcporter call <server.tool> key=value # 调用工具（键值对语法）
mcporter call "<server.tool>(k: v)" # 调用工具（函数语法）
mcporter call <server.tool> –args '{}'# 调用工具（JSON 参数）
mcporter call –stdio "<command>" <tool> key=value # Ad-hoc stdio
mcporter call <url.tool> key=value # Ad-hoc HTTP
mcporter call <server.tool> –output json # JSON 格式输出
mcporter call <server.tool> –tail-log # 显示调用日志

# === 配置 ===
mcporter config list # 列出配置
mcporter config get <server> # 查看某个服务器配置
mcporter config add <name> –stdio "cmd" –env K=V # 添加
mcporter config remove <name> # 删除
mcporter config import cursor # 从 Cursor 导入
mcporter config import claude-code # 从 Claude 导入

# === 认证 ===
mcporter auth <server> # OAuth 认证
mcporter auth <url> # 对远程 URL 认证
mcporter auth <server> –reset # 重置认证

# === Daemon ===
mcporter daemon start # 启动后台服务
mcporter daemon status # 查看状态
mcporter daemon stop # 停止
mcporter daemon restart # 重启

# === 代码生成 ===
mcporter generate-cli –server <name> # 生成独立 CLI
mcporter generate-cli –command <url> # 从 URL 生成
mcporter emit-ts <server> –mode types # 生成 TypeScript 类型
mcporter emit-ts <server> –mode client # 生成 TypeScript 客户端
mcporter inspect-cli <path> # 检查已生成的 CLI

📚 参考资料

• McPorter GitHub 仓库
• McPorter npm 包
• McPorter CLI 参考文档
• McPorter 配置文档
• OpenClaw 配置文档
• OpenClaw MCP 集成文档
• MCP 官方 Server 仓库
• ClawHub — OpenClaw Skills 注册表

如果觉得有帮助，欢迎 点赞 👍 收藏 ⭐ 关注 🔔，有问题评论区见！

本文为原创内容，转载请注明出处。