claude-channel

基于 Bun + TypeScript 的 stdio MCP 服务，作用是把外部 OpenAI Chat Completions 请求转发到 Claude Code 的 channels，再把 Claude Code 回复回写给 API 调用方。

功能

• MCP 服务通过 stdio 运行，可直接被 Claude Code 接入。
• 声明 experimental["claude/channel"]，支持 notifications/claude/channel。
• 提供 OpenAI 兼容 HTTP API：POST /v1/chat/completions。
• 外部请求进入后：
  1. 转成 channel 消息发给 Claude Code
  2. Claude Code 调用 channel_reply 返回内容
  3. MCP 服务把结果封装成 OpenAI Chat Completions 响应返回

整体调用流程图

架构视图

flowchart LR
    App[其他应用]
    API[OpenAI Compatible API<br/>/v1/chat/completions<br/>/v1/models]
    MCP[claude-channel MCP Server<br/>stdio + channel bridge]
    Claude[Claude Code]

    App --> API
    API --> MCP
    MCP --> Claude
    Claude --> MCP
    MCP --> API
    API --> App

Loading

时序视图

sequenceDiagram
    participant App as 其他应用
    participant API as claude-channel HTTP API
    participant MCP as claude-channel MCP (stdio)
    participant Claude as Claude Code

    Claude->>MCP: 启动并接入 MCP
    Claude->>MCP: http_server_start (或 BRIDGE_HTTP_AUTO_START=1)
    App->>API: POST /v1/chat/completions
    API->>MCP: 创建 pending request_id
    MCP-->>Claude: notifications/claude/channel<br/><channel source=claude-channel ...>
    Claude->>MCP: 调用 channel_reply(request_id, content)
    MCP->>API: 匹配 request_id，回填回复
    API-->>App: OpenAI Chat Completions 响应

    App->>API: GET /v1/models
    API-->>App: 模型列表 (claude-channel)

Loading

安装

bun install

运行

bun run src/index.ts

这是一个 stdio MCP 进程，通常由 Claude Code 拉起。

Claude Code 接入示例

.mcp.json 示例：

{
  "mcpServers": {
    "claude-channel": {
      "command": "bun",
      "args": ["run", "/ABS/PATH/TO/claude-channel/src/index.ts"]
    }
  }
}

可用工具

• http_server_start：开启 OpenAI 兼容 HTTP 服务
• http_server_stop：停止 HTTP 服务
• http_server_status：查看服务状态
• runtime_status：查看 MCP 运行状态（含监听 host/port、listen_url、pending 请求数、OpenAI routes 和模型列表）
• channel_debug_events：调试查看输入输出事件，包括进入 channels 的消息、Claude 回包、以及发给 OpenAI 客户端的响应；支持按 request_id、kind、source_type、stream 过滤，以及 limit
• channel_reply：Claude Code 用它回复某个 request_id
• channel_reply_stream：流式回复工具（按 request_id 多次发送 delta，最后 done=true）
• channel_publish：手动发送测试 channel

HTTP API

健康检查

curl http://127.0.0.1:8787/health

Models

curl http://127.0.0.1:8787/v1/models

Chat Completions

curl -X POST http://127.0.0.1:8787/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-channel",
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "你好，介绍一下你是谁"}
    ]
  }'

Chat Completions (stream)

curl -N -X POST http://127.0.0.1:8787/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "claude-channel",
    "stream": true,
    "messages": [
      {"role": "user", "content": "请分三段介绍你自己"}
    ]
  }'

提示：如果上游一次回传整段 delta，可通过 BRIDGE_STREAM_EMIT_CHUNK_SIZE、BRIDGE_STREAM_EMIT_INTERVAL_MS、BRIDGE_STREAM_EMIT_PUNCT_PAUSE_MS 在服务端二次切片，前端会看到更连续、更接近打字机的流式输出。

开启 API Key 校验

启动前设置：

export BRIDGE_API_KEY='your-token'

请求时：

-H 'Authorization: Bearer your-token'

环境变量

• BRIDGE_HTTP_HOST：默认 127.0.0.1
• BRIDGE_HTTP_PORT：默认 8787
• BRIDGE_CHAT_TIMEOUT_MS：默认 180000
• BRIDGE_API_KEY：可选，设置后启用 Bearer 校验
• BRIDGE_HTTP_AUTO_START=1：MCP 连接后自动启动 HTTP 服务
• BRIDGE_STREAM_EMIT_CHUNK_SIZE：stream 输出切片大小（按字符切分，默认 3）
• BRIDGE_STREAM_EMIT_INTERVAL_MS：stream 每个切片之间的基础间隔毫秒（默认 28）
• BRIDGE_STREAM_EMIT_PUNCT_PAUSE_MS：遇到句号/问号/叹号等标点时的额外停顿（默认 90）

交互约定

当外部请求到达时，Claude Code 会收到形如：

<channel source="claude-channel" request_id="...">...</channel>

Claude Code 需要调用 channel_reply：

• request_id：来自 channel 属性
• content：要回给 API 客户端的文本