mcporter — 安装部署及使用完全指南（一）

海兰2026-08-16 9:40

MCP, made portable.

让 AI 代理和开发者无需编写样板代码，即可调用任何 MCP 服务器。

一、概述

1.1 mcporter

mcporter 是一个 TypeScript 运行时、CLI 和代码生成工具包，专为 Model Context Protocol (MCP) 设计。它让 AI 代理和开发人员无需编写样板代码即可调用任何 MCP 服务器。

属性 说明
🏠 官网 https://mcporter.sh/
🐙 GitHub https://github.com/openclaw/mcporter
📦 包管理器 npm / pnpm / Bun / Homebrew
🎯 Node.js 要求 Node.js 24+
🖥️ 平台 macOS (arm64 / x86_64), Linux, Windows (WSL)

1.2 "Porter"

🚂 Porter（行李员） 在火车站之间搬运行李。mcporter 对 MCP 服务器做同样的事情：它在你的代理（或终端）和另一端的 MCP 服务器之间搬运工具调用、Schema、OAuth 令牌和 stdio 句柄。你无需提前了解服务器的具体形状，运行时保持连接温热，重复调用成本极低。

1.3 mcporter 能做的

分类 功能
发现与连接 🔍 自动发现 Cursor / Claude / Codex / Windsurf / OpenCode / VS Code 中的 MCP 服务器
🔌 支持 stdio / HTTP / SSE 三种传输协议
🔑 内置 OAuth 认证与令牌刷新
调用与交互 🛠️ 调用 MCP 工具（多种参数语法）
📄 读取 MCP 资源
🎨 多种输出格式（text / markdown / json / raw）
代码生成 🏗️ 生成独立 CLI（可打包为单文件）
📝 生成 TypeScript 类型定义和客户端
运行时与桥接 ⚡ Keep-Alive 守护进程（保持状态连接）
🌉 MCP 桥接（将多个服务器暴露为单个 MCP 服务器）

1.4 适配 Agent

mcporter 遵循 Anthropic 推荐的 "code-execution-with-MCP" 模式：

跳过庞大的工具 Schema 提示词，生成一个小的类型化表面，让代理或人类像调用普通函数一样调用 MCP 服务器。

推荐工作流：
#mermaid-svg-bfSQa0OfJa3ivls3{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-bfSQa0OfJa3ivls3 .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-bfSQa0OfJa3ivls3 .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-bfSQa0OfJa3ivls3 .error-icon{fill:#552222;}#mermaid-svg-bfSQa0OfJa3ivls3 .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-bfSQa0OfJa3ivls3 .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-bfSQa0OfJa3ivls3 .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-bfSQa0OfJa3ivls3 .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-bfSQa0OfJa3ivls3 .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-bfSQa0OfJa3ivls3 .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-bfSQa0OfJa3ivls3 .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-bfSQa0OfJa3ivls3 .marker{fill:#333333;stroke:#333333;}#mermaid-svg-bfSQa0OfJa3ivls3 .marker.cross{stroke:#333333;}#mermaid-svg-bfSQa0OfJa3ivls3 svg{font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-bfSQa0OfJa3ivls3 p{margin:0;}#mermaid-svg-bfSQa0OfJa3ivls3 .label{font-family:"trebuchet ms",verdana,arial,sans-serif;color:#333;}#mermaid-svg-bfSQa0OfJa3ivls3 .cluster-label text{fill:#333;}#mermaid-svg-bfSQa0OfJa3ivls3 .cluster-label span{color:#333;}#mermaid-svg-bfSQa0OfJa3ivls3 .cluster-label span p{background-color:transparent;}#mermaid-svg-bfSQa0OfJa3ivls3 .label text,#mermaid-svg-bfSQa0OfJa3ivls3 span{fill:#333;color:#333;}#mermaid-svg-bfSQa0OfJa3ivls3 .node rect,#mermaid-svg-bfSQa0OfJa3ivls3 .node circle,#mermaid-svg-bfSQa0OfJa3ivls3 .node ellipse,#mermaid-svg-bfSQa0OfJa3ivls3 .node polygon,#mermaid-svg-bfSQa0OfJa3ivls3 .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-bfSQa0OfJa3ivls3 .rough-node .label text,#mermaid-svg-bfSQa0OfJa3ivls3 .node .label text,#mermaid-svg-bfSQa0OfJa3ivls3 .image-shape .label,#mermaid-svg-bfSQa0OfJa3ivls3 .icon-shape .label{text-anchor:middle;}#mermaid-svg-bfSQa0OfJa3ivls3 .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-bfSQa0OfJa3ivls3 .rough-node .label,#mermaid-svg-bfSQa0OfJa3ivls3 .node .label,#mermaid-svg-bfSQa0OfJa3ivls3 .image-shape .label,#mermaid-svg-bfSQa0OfJa3ivls3 .icon-shape .label{text-align:center;}#mermaid-svg-bfSQa0OfJa3ivls3 .node.clickable{cursor:pointer;}#mermaid-svg-bfSQa0OfJa3ivls3 .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-bfSQa0OfJa3ivls3 .arrowheadPath{fill:#333333;}#mermaid-svg-bfSQa0OfJa3ivls3 .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-bfSQa0OfJa3ivls3 .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-bfSQa0OfJa3ivls3 .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bfSQa0OfJa3ivls3 .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-bfSQa0OfJa3ivls3 .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bfSQa0OfJa3ivls3 .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-bfSQa0OfJa3ivls3 .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-bfSQa0OfJa3ivls3 .cluster text{fill:#333;}#mermaid-svg-bfSQa0OfJa3ivls3 .cluster span{color:#333;}#mermaid-svg-bfSQa0OfJa3ivls3 div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:"trebuchet ms",verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-bfSQa0OfJa3ivls3 .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-bfSQa0OfJa3ivls3 rect.text{fill:none;stroke-width:0;}#mermaid-svg-bfSQa0OfJa3ivls3 .icon-shape,#mermaid-svg-bfSQa0OfJa3ivls3 .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-bfSQa0OfJa3ivls3 .icon-shape p,#mermaid-svg-bfSQa0OfJa3ivls3 .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-bfSQa0OfJa3ivls3 .icon-shape .label rect,#mermaid-svg-bfSQa0OfJa3ivls3 .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-bfSQa0OfJa3ivls3 .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-bfSQa0OfJa3ivls3 .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-bfSQa0OfJa3ivls3 :root{--mermaid-font-family:"trebuchet ms",verdana,arial,sans-serif;} 配置 MCP 服务器
mcporter list 查看工具签名
mcporter emit-ts 生成类型
编写小型 per-server Agent 技能
mcporter call 调用工具
需要分享？

mcporter generate-cli

二、安装

2.1 🚀 无需安装即可试用（推荐首次使用）

bash 复制代码 
# 查看版本
npx mcporter --version

# 列出所有已发现的 MCP 服务器
npx mcporter list

💡 npx 会将包保留在 npm 缓存中，后续运行即时执行。这是推荐的第一步。

2.2 📦 npm / pnpm / Bun 安装

全局安装（推荐日常 CLI 使用）：

bash 复制代码 
npm install -g mcporter

项目内安装（推荐在 TypeScript 项目中使用运行时 API）：

bash 复制代码 
pnpm add mcporter        # 或: npm install mcporter / bun add mcporter

📌 要求 : Node.js 24+。Bun 下也可运行。

包同时暴露可导入的运行时（createRuntime、callOnce、createServerProxy）和 mcporter CLI 二进制文件。

2.3 🍺 Homebrew（macOS）

bash 复制代码 
brew install steipete/tap/mcporter

如果之前从旧 tap 安装过，先运行 brew update 再重新安装，确保 Homebrew 能识别新的 formula 路径。

2.4 💾 独立二进制文件（macOS）

每个发布版本提供针对 macOS arm64 和 x86_64 的 Bun 编译独立二进制文件：

架构 文件名
Apple Silicon (M1/M2/M3/M4) mcporter_<version>_darwin_arm64.tar.gz
Intel Mac mcporter_<version>_darwin_x86_64.tar.gz

安装步骤：

  1. 从 GitHub Releases 下载对应架构的 tar.gz
  2. 用 checksums.txt 验证文件完整性
  3. 解压到 $PATH 中的目录（如 ~/.local/bin/）

🔒 官方 macOS 二进制使用 OpenClaw Foundation Developer ID 团队 FWJYW4S8P8 进行代码签名和 Apple 公证，包含硬化运行时和时间戳。provenance.json 记录了签名标签、提交哈希、构建器版本等元数据。

2.5 ✅ 验证安装

bash 复制代码 
mcporter --version
mcporter list

第一次运行会打印 mcporter 从各个配置中发现的 MCP 服务器。如果没有任何输出，说明还没有配置服务器，继续往下看 👇。

2.6 🔄 更新

安装方式 更新命令
npm npm install -g mcporter@latest
pnpm pnpm up -g mcporter@latest
Homebrew brew upgrade steipete/tap/mcporter
独立二进制 下载新版本替换旧文件

2.7 🗑️ 卸载

bash 复制代码 
# npm
npm uninstall -g mcporter

# Homebrew
brew uninstall steipete/tap/mcporter

# 独立二进制：删除 $PATH 中的文件

🧹 mcporter 将 OAuth 令牌和缓存 Schema 存储在 ~/.mcporter/（或 $XDG_CACHE_HOME/mcporter/）。如需完全清除，手动删除该目录。

三、快速入门：5 分钟上手

本教程使用公开的 Context7 MCP 服务器，无需现有 MCP 配置即可跟随操作。

3.1 添加 Context7 服务器

bash 复制代码 
npx mcporter config add context7 https://mcp.context7.com/mcp --scope home

--scope home 将配置保存到用户目录（~/.mcporter/mcporter.json），不影响项目配置。

3.2 列出所有已发现的 MCP 服务器

bash 复制代码 
npx mcporter list

输出每行一个服务器，包含认证状态 🔐、传输类型 📡 和工具数量 🔢。常用标志：

标志 说明
--json 机器可读 JSON 输出
--quiet 静默健康检查
--verbose 查看每个服务器的注册来源

3.3 查看单个服务器的工具签名

bash 复制代码 
npx mcporter list context7

输出类似 TypeScript 头文件：带 /** ... */ 文档注释的 function name(...) 签名。可选参数被精简以保持屏幕可读性。

进阶标志：

标志 说明
--brief / --signatures 仅显示紧凑签名
--all-parameters 显示所有可选参数
--schema 格式化打印 JSON Schema
--json 机器可读 Schema
--status 仅状态摘要

3.4 调用工具

bash 复制代码 
# 冒号分隔标志（shell 友好）
npx mcporter call context7.resolve-library-id   query:'React hooks docs'   libraryName:react

# 函数调用风格（可直接从 mcporter list 输出复制）
npx mcporter call 'context7.resolve-library-id(query: "React hooks docs", libraryName: "react")'

3.5 选择输出格式

bash 复制代码 
# 纯文本（默认）
npx mcporter call context7.resolve-library-id query:react --output text

# Markdown
npx mcporter call context7.resolve-library-id query:react --output markdown

# JSON（适合管道处理）
npx mcporter call context7.resolve-library-id query:react --output json

# 原始输出
npx mcporter call context7.resolve-library-id query:react --output raw

💡 --json 在 stdout 生成稳定 JSON 信封；人类可读的进度、提示和警告始终输出到 stderr，确保管道解析不受影响。

3.6 读取 MCP 资源

bash 复制代码 
# 列出资源
npx mcporter resource my-resource-server

# 读取特定资源
npx mcporter resource my-resource-server file:///path/to/spec.md

3.7 生成独立 CLI

当你想分享一个工具给不需要学习 mcporter call 的人：

bash 复制代码 
npx mcporter generate-cli context7   --runtime node   --bundler rolldown   --bundle dist/context7.js

# 使用生成的 CLI
node dist/context7.js resolve-library-id --query 'React hooks docs' --library-name react

3.8 生成类型化客户端

bash 复制代码 
# 仅类型定义
npx mcporter emit-ts context7 --mode types --out types/context7-tools.d.ts

# 完整客户端（含工厂函数）
npx mcporter emit-ts context7 --mode client --out src/context7-client.ts
相关推荐
skywalk816343 分钟前
用WorkBuddy成功把Deepseek Harness移植到FreeBSD
人工智能·deepseek·harness
JavaPub-rodert43 分钟前
我把 OpenAI 协议塞进了 Go 工具库：go-commons 开始支持 AI 了
开发语言·人工智能·golang
HZZD_HZZD1 小时前
非侵入式负荷监测选`Seq2Point`还是`LSTM`？合众致达实测：洗衣机分解F1达0.87、`NDE`误差降27%，附PyTorch完整实现
人工智能·pytorch·lstm
嘟哩DuliDuli1 小时前
AI 账单变高的技术原因：重复上下文和用量归属
android·人工智能·安全·ai·软件工程
Tom·Ge1 小时前
AI创业者通识日报 | 2026年8月13日
人工智能·大模型·ai创业·ai创业者
tech讯息1 小时前
企业 AI 办公平台如何标准化落地？哪些云方案适配企业统一部署？—— 优先评估统一工作台、权限管控与系统集成能力
人工智能
IT_陈寒1 小时前
搞不定JavaScript的数组去重？你可能漏了这两个坑
前端·人工智能·后端
豌豆学姐1 小时前
likeadmin-api 全驱动数字人参数避坑：file_url、ref_file_url 和 mode 怎么传
人工智能·aigc·api·数字人·全驱动数字人
海兰1 小时前
mcporter — 安装部署及使用完全指南（四）
人工智能·agent·openclaw
热门推荐
01GitHub 镜像站点02国内可直接用、免费额度/永久免费的大模型API清单（含 SiliconFlow、火山、阿里、智谱、百度、Kimi、DeepSeek、DMXAPI 等）03微信历史版本含下载地址（ Windows PC | 安卓 | MAC ）及设置微信不更新042026 国产 AI 大模型横评：DeepSeek、通义千问、Kimi、文心一言、星火、豆包谁更能打？05Agnes AI 免费 API 接入指南：文本、生图、生视频，一套接口全免费06VSCode+CodeX扩展，无法启动07历年考研数学一、数学二、数学三真题试卷及答案PDF08AI 编程 IDE 全景解析 2026：Agent 全面接管开发链路092026年7月AI圈大地震：GPT-5.6被政府限制、Claude入驻Slack、Anthropic自研芯片10如何新建文件夹？ 电脑新建文件夹的4种方法