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

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

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

📑 文章目录

1. [痛点：MCP 服务器配好了，然后呢？](#痛点：MCP 服务器配好了，然后呢？)
2. [McPorter 是什么：MCP 的统一 CLI 运行时](#McPorter 是什么：MCP 的统一 CLI 运行时)
3. [McPorter vs 手动配置 vs OpenClaw Skills：三者关系](#McPorter vs 手动配置 vs OpenClaw Skills：三者关系)
4. [安装 McPorter](#安装 McPorter)
5. 核心命令速查：list、call、config、auth
6. [实战一：列出所有可用的 MCP 服务器和工具](#实战一：列出所有可用的 MCP 服务器和工具)
7. [实战二：从终端直接调用 MCP 工具](#实战二：从终端直接调用 MCP 工具)
8. [实战三：添加和管理 MCP 服务器配置](#实战三：添加和管理 MCP 服务器配置)
9. [实战四：OAuth 认证与远程 MCP 服务器](#实战四：OAuth 认证与远程 MCP 服务器)
10. [进阶：生成 TypeScript 客户端和独立 CLI](#进阶：生成 TypeScript 客户端和独立 CLI)
11. [McPorter + OpenClaw：联合使用最佳实践](#McPorter + OpenClaw：联合使用最佳实践)

---

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 服务器包，也不是注册表/商店。它的核心能力是：

能力	说明	类比
🔍 发现	自动检测你已配置的所有 MCP 服务器	类似 docker ps
📞 调用	从终端直接调用任意 MCP 工具	类似 curl
🔑 认证	管理 OAuth 流程和 token 缓存	类似 aws configure
⚙️ 配置	统一管理多来源的 MCP 配置	类似 git config
🏭 生成	为 MCP 工具生成独立 CLI 或 TypeScript 类型	类似 protoc

零配置自动发现

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.json	OpenClaw Skills (ClawHub)	McPorter
是什么	直接编辑 JSON5 配置	Agent 行为增强包	MCP CLI 运行时
管理对象	MCP Server 配置	Skills（可内嵌 MCP）	MCP Server 调用与配置
安装 MCP 包	✅ 手动配置	✅ Skill 内声明自动配置	❌ 不负责安装
直接调用工具	❌ 只能通过 Agent	❌ 只能通过 Agent	✅ mcporter call
跨应用发现	❌ 仅 OpenClaw	❌ 仅 OpenClaw	✅ Cursor/Claude/Codex 等
OAuth 管理	❌ 手动	部分支持	✅ mcporter auth
TypeScript API	❌	❌	✅ 完整 SDK
CLI 生成	❌	❌	✅ mcporter generate-cli

它们的关系

┌─────────────────────────────────────────────────┐
│               你的工作环境                        │
│                                                 │
│   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 注册表

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

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