mcporter-bridge

Expose your local MCPorter registry as one stable MCP server for coding clients.

mcporter-bridge is a small FastMCP server that turns your existing mcporter setup into a single, reusable entry point for clients like Codex, Claude Code, Cline, and Cursor.

Why

If you use multiple coding clients, your MCP setup usually fragments fast:

• Codex has one config format

• Claude Code has another

• Cline and Cursor add their own

• mcporter already knows your real server registry, auth state, and runtime

mcporter-bridge keeps mcporter as the source of truth and gives clients one stable MCP server instead of another pile of duplicated configs.

What It Does

• Reads your local mcporter registry at runtime

• Lists configured MCP servers and their health

• Inspects a specific server and its tool schemas

• Calls any tool on any configured server through mcporter

• Lazy loading: Activate/deactivate heavy MCPs on demand to save context

• Optionally exposes local agent-reach diagnostics as helper tools

This is not a transport proxy and not an enterprise gateway. It is a local-first bridge for client integration.

Tools

Core Tools

Lazy Loading Tools (按需加载)

Utility Tools

All tools return structured output with:

• ok

• timed_out

• command

• timeout_ms

• returncode

• stdout

• stderr

• parsed_json

Install

pip

pip install mcporter-bridge

pipx

pipx install mcporter-bridge

After installation, you get two commands:

• mcporter-bridge to run the MCP server

• mcporter-bridge-config to generate or install client snippets

local development

git clone https://github.com/Citrus086/mcporter-bridge.git
cd mcporter-bridge
python3 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Requirements

• mcporter installed and available on PATH

• at least one configured MCP server in your local mcporter registry

Optional:

Quick Check

mcporter-bridge

In another shell:

mcporter list --stdio "python3 -m mcporter_bridge" --json

Client Setup

Ready-made templates live in examples/.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.mcporter-bridge]
type = "stdio"
command = "python3"
args = ["-m", "mcporter_bridge"]
startup_timeout_ms = 30000

Or install it automatically:

mcporter-bridge-config install --client codex

Notes:

• OpenAI’s docs confirm that Codex reads MCP config from ~/.codex/config.toml using the mcp_servers.<name> structure for MCP servers.

• The stdio form here is also verified locally with codex mcp add --help, which accepts codex mcp add <name> -- <command...> for stdio servers.

Claude Code / Claude Desktop

Add this to your MCP config:

{
  "mcpServers": {
    "mcporter-bridge": {
      "command": "python3",
      "args": ["-m", "mcporter_bridge"]
    }
  }
}

Automatic install using the default ~/.claude.json path:

mcporter-bridge-config install --client claude

Notes:

• Anthropic’s Claude Code docs confirm that user-scoped MCP servers live in ~/.claude.json.

• The same docs show project-scoped servers stored in .mcp.json at the project root.

• The documented JSON shape uses mcpServers with command, args, and env for stdio servers.

Cline

Use the same stdio shape:

{
  "mcpServers": {
    "mcporter-bridge": {
      "command": "python3",
      "args": ["-m", "mcporter_bridge"]
    }
  }
}

Generate snippets:

mcporter-bridge-config snippet --client cline

Write to an explicit config path:

mcporter-bridge-config install --client cline --config-path /path/to/mcp.json

Notes:

• Cline’s docs confirm that MCP settings are stored in cline_mcp_settings.json.

• For local stdio servers, the documented JSON shape uses mcpServers with command, args, env, alwaysAllow, and disabled.

• Cline’s docs use type for remote transport config such as streamableHttp, but not in the local stdio example, so the bridge does not emit type for Cline.

Cursor

Cursor uses mcp.json with mcpServers, and for stdio servers the bridge emits type: "stdio" explicitly.

Global config example:

{
  "mcpServers": {
    "mcporter-bridge": {
      "type": "stdio",
      "command": "python3",
      "args": ["-m", "mcporter_bridge"]
    }
  }
}

Install into the default global path:

mcporter-bridge-config install --client cursor

Or write to an explicit config path:

mcporter-bridge-config install --client cursor --config-path /path/to/mcp.json

Config Helper

Print a snippet:

mcporter-bridge-config snippet --client codex

Customize the launcher:

mcporter-bridge-config snippet \
  --client claude \
  --python-command /opt/homebrew/bin/python3.13 \
  --module-name mcporter_bridge

Install directly into a config file:

mcporter-bridge-config install --client codex
mcporter-bridge-config install --client claude

When an existing config file is updated, the helper writes a sibling backup with a .bak suffix first.

Example Prompts

• "列出所有可用的 MCP 服务器"

• "查看 xiaohongshu 服务器的工具"

• "调用 xiaohongshu 的 check_login_status"

• "激活 playwright 浏览器工具"

• "查看 xiaohongshu 的原始工具定义（raw=true）"

Lazy Loading (按需加载)

大型 MCP 如 chrome-devtools (29 tools) 或 playwright (22 tools) 会消耗大量上下文。默认保持未加载状态，需要时再激活。

MCP 类型

• small - 小型 MCP，通常已加载，可直接使用

• heavy - 大型 MCP，默认未加载，需先激活

Setup

1. 创建 heavy MCP 目录：

mkdir -p ~/.mcporter/heavy/available

2. 将大型 MCP 从 mcporter.json 移到单独文件：

# 示例：将 playwright 移到 heavy
echo '{
  "mcpServers": {
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"],
      "description": "浏览器自动化",
      "tags": ["浏览器"]
    }
  }
}' > ~/.mcporter/heavy/available/playwright.json

3. 从主 mcporter.json 中移除该 MCP。

Workflow

1. mcporter_list_servers()
   ↓ 返回 active（已加载）和 available（可激活）两个列表
   ↓ 需要的 MCP 在 available 中？
2. mcporter_activate_mcp(name="playwright")
   ↓
3. mcporter_list_servers()  # 确认已出现在 active 列表
   ↓
4. 使用 playwright 工具...
   ↓
5. mcporter_deactivate_mcp(name="playwright")  # 用完即释放

这让上游 LLM 能够自我管理上下文，按需加载/卸载大型 MCP。

Server Descriptions (服务器描述)

mcporter-bridge 会为每个 MCP 服务器提供功能描述，帮助 LLM 了解每个服务是干什么的。

描述来源（优先级从高到低）

1. 用户配置 - 在 ~/.mcporter/mcporter.json 中添加

2. 内置映射 - 常见 MCP 的预设描述

3. 名字推断 - 从服务器名称猜测功能

在 mcporter.json 中配置描述

{
  "mcpServers": {
    "my-custom-mcp": {
      "command": "...",
      "args": [...],
      "description": "自定义 MCP 的功能描述",
      "tags": ["标签1", "标签2"],
      "best_for": "最适合的使用场景"
    }
  }
}

内置描述的常见 MCP

名字推断规则

如果服务器不在内置列表中，会从名称推断：

• 包含 search → 搜索相关

• 包含 browser / chrome → 浏览器相关

• 包含 github / git → 代码仓库相关

• 包含 xiaohongshu → 小红书相关

• ...

Environment Variables

• MCPORTER_BRIDGE_MCPORTER_BIN: override the mcporter binary path

• MCPORTER_BRIDGE_MAX_OUTPUT_CHARS: cap captured stdout/stderr length

Troubleshooting / 一个跨三层的隐蔽 bug

如果你在 macOS + Anaconda Python 环境下遇到 ModuleNotFoundError: No module named mcporter_bridge，或者 Claude 一直报 Failed to reconnect，问题可能来自一个跨三层的隐蔽 bug：

pip 写入 .pth 文件
    ↓
macOS 自动给该文件打上 UF_HIDDEN flag（因为父目录 .venv 被标记为隐藏）
    ↓
Anaconda Python 的 site.py 读取 .pth 时，检测到 UF_HIDDEN 就直接跳过
    ↓
Editable install 失效，import mcporter_bridge 失败

这会导致 python3 -m mcporter_bridge 直接起不来进程，Claude 等 MCP 客户端自然无法重连。

我们已经做的修复

• __main__.py 里加了 bootstrap fallback：如果模块加载失败，会自动探测 src/ 目录并注入 sys.path。

• mcporter-bridge-config 在生成客户端配置时，自动检测 editable install 并写入 PYTHONPATH，同时写入 FASTMCP_SHOW_SERVER_BANNER=false 保证 stdio 干净。

• show_banner=False：确保 FastMCP 的启动 banner 不会污染 stdio 的 JSON-RPC 输出。

临时 workaround

如果你不想重新安装，可以手动去掉 hidden flag：

chflags nohidden /path/to/your/.venv/lib/python3.12/site-packages/_mcporter_bridge.pth

或者直接给 Claude/Codex 等客户端的 env 加上：

"env": {
  "PYTHONPATH": "/absolute/path/to/mcporter-bridge/src",
  "FASTMCP_SHOW_SERVER_BANNER": "false"
}

这个 bug 的诡异之处在于：pip、macOS、Python 三层单独看都没错，但串在一起就把 editable install 干掉了。更让人意外的是，我们项目的 build backend hatchling 目前并不支持 symlink editable mode，所以即使想绕过 .pth 文件也做不到——它只能生成 .pth 文件。目前 Python 和 macOS 官方 issue tracker 里似乎还没有人专门报告这一现象。

Roadmap

• higher-level convenience tools for common MCPs

• optional tool allowlists / denylists

• more client-specific path discovery

• richer auth and diagnostics helpers

License

MIT