Herald - The Self Hosted Mcp Bridge Between Claude Chat And Claude Code

Herald

用手机写代码。真的。
连接 Claude Chat 与 Claude Code 的可自托管 MCP 桥接工具。

文档 · 快速开始 · 工作原理 · 功能 · 安全 · 路线图
🇫🇷 法语版本

你正窝在沙发上，手里拿着手机。你打开 Claude Chat 并输入：

“将 my-api 中的身份验证中间件重构为使用 JWT，而不是会话 Cookie。运行测试。”

四分钟后，任务完成。已创建分支、重构代码、测试通过，并提交了更改。所有工作都由你的工作站完成。你甚至没打开笔记本电脑。

这就是 Herald。

问题

Claude Chat 和 Claude Code 是两款出色的工具，却各自运行在完全独立的世界里。

你一直在两者之间复制粘贴。或者更糟——你一直等到回到办公桌前才开始处理。这种情况到此为止。

解决方案

Herald 是一个可自托管的 MCP 服务，通过 Anthropic 官方的 Custom Connectors 协议将 Claude Chat 连接到 Claude Code。一个 Go 二进制文件，零 hack。

  You (phone/tablet/browser)
       │
       │  "Add rate limiting to the API"
       ▼
  Claude Chat ──── MCP over HTTPS ────► Herald (your workstation)
                                           │
                                           ▼
                                        Claude Code
                                           ├── reads your codebase
                                           ├── writes the code
                                           ├── runs the tests
                                           └── commits to a branch

  You (terminal)
       │
       │  Claude Code calls herald_push
       ▼
  Claude Code ──── MCP ────► Herald ────► Claude Chat picks it up
                                           └── session context, summary,
                                               files modified, git branch

这个桥接工具是双向的。Claude Chat 可以向 Claude Code 分派任务，而 Claude Code 也可以将会话上下文推送回 Herald，以便远程监控，并从其他设备继续会话。

你的代码绝不会离开本机。Herald 只负责协调。

工作原理

You (Claude Chat)          Herald                     Claude Code
─────────────────          ──────                     ───────────
"Refactor auth..."    ──►  start_task
                           → creates branch
                           → spawns Claude Code  ──►  reads codebase
                                                      refactors code
                                                      runs tests
                                                      commits changes
                      ◄──  task_id: herald-a1b2c3d4

"How's it going?"     ──►  check_task
                      ◄──  ✅ Completed (4m 12s)
                           4 files changed (+127/-23)

"Show me the diff"    ──►  get_diff
                      ◄──  auth/middleware.go
                           +func ValidateJWT(...)
                           -func CheckSession(...)

三个工具，就是核心工作流程。启动、检查、获取结果——无论你身在何处，都能完成。

反向流程：Claude Code → Herald

在终端中工作时，如果想在手机上继续，可以让 Claude Code 将会话推送到 Herald：

You (terminal)             Claude Code                Herald
──────────────             ───────────                ──────
"Push this to Herald"  ──►  herald_push
                             → session_id, summary,
                               files, branch       ──►  linked task created
                                                         🔗 visible in list_tasks

You (phone, later)         Claude Chat                Herald
──────────────────         ───────────                ──────
"What sessions are         list_tasks
 waiting for me?"     ──►  (status: linked)      ──►  🔗 herald-a1b2c3d4
                                                         my-api / feat/auth

"Resume that session"  ──► start_task
                            (session_id)          ──►  picks up where you left off

功能

核心功能

• 原生 MCP 桥接 — 使用 Anthropic 官方的 Custom Connectors 协议。不是 hack，不是封装器，也不是代理。
• 异步任务执行 — 启动任务、查看进度、获取结果。Claude Code 会在后台运行，你可以同时处理其他事情。
• Git 分支隔离 — 每个任务都在独立分支上运行，不会触碰主分支。
• 会话续接 — 支持多轮 Claude Code 对话。可以从上次中断处继续。
• 双向桥接 — Claude Code 可以通过 herald_push 将会话上下文推送到 Herald，以便远程监控，并从其他设备继续会话。

多项目支持

• 多个项目 — 按需配置任意数量的项目，每个项目都有自己的设置。
• 按项目限制工具 — 精确控制 Claude Code 可使用的工具。每个项目都拥有完整的沙盒隔离。

运维

• MCP 推送通知 — Herald 通过 MCP 服务通知将任务更新直接推送到 Claude Chat。无需轮询。
• SQLite 持久化 — 即使服务重启，任务也会保留。完整历史记录，且支持全面搜索。

工程

• 单一二进制文件 — 一个 Go 可执行文件，约 15MB。无需 Docker、运行时或 node_modules。
• 零 CGO — 纯 Go。可交叉编译为 Linux、macOS、Windows 和 ARM 版本。
• 6 个依赖项 — chi、mcp-go、modernc/sqlite、uuid、yaml、testify。这就是全部依赖树。

快速开始

前置条件：Claude Code CLI 已安装，并通过 ngrok（内置）或带反向代理的域名提供 HTTPS。

1. 安装

curl -fsSL https://raw.githubusercontent.com/btouchard/herald/main/install.sh | sh

git clone https://github.com/btouchard/herald.git
cd herald && make build
# Binary is in ./bin/herald

2. 配置

mkdir -p ~/.config/herald
cp configs/herald.example.yaml ~/.config/herald/herald.yaml
# Edit with your domain and projects (see below)

3. 运行

herald serve
# Client secret is auto-generated on first start and displayed in the console

编辑 ~/.config/herald/herald.yaml，填写你的域名和项目：

server:
  host: "127.0.0.1"
  port: 8420
  public_url: "https://herald.yourdomain.com"

auth:
  client_id: "herald-claude-chat"

projects:
  my-api:
    path: "/home/you/projects/my-api"
    description: "Main backend API"
    default: true
    allowed_tools:
      - "Read"
      - "Write"
      - "Edit"
      - "Bash(git *)"
      - "Bash(go *)"
      - "Bash(make *)"
    git:
      auto_branch: true
      branch_prefix: "herald/"

然后从 Claude Chat 连接：

1. Claude Chat → 设置 → 自定义连接器
2. 添加连接器：https://herald.yourdomain.com/mcp
3. 通过 OAuth 进行身份验证
4. 完成 — Claude Chat 现在有 10 个新工具可用于控制你的工作站

使用 ngrok 快速开始（无需反向代理）

没有域名或反向代理？使用 ngrok，即可通过 HTTPS 立即公开 Herald：

1. 获取 ngrok 身份验证令牌

在 ngrok.com 注册（免费套餐即可），并从控制面板获取身份验证令牌。

2. 在配置中启用隧道

编辑 ~/.config/herald/herald.yaml：

tunnel:
  enabled: true
  provider: "ngrok"
  authtoken: "2abc..."  # or set HERALD_NGROK_AUTHTOKEN env var
  # domain: "my-herald.ngrok-free.app"  # optional: fixed domain (paid plans)

3. 运行 Herald

herald serve
# Tunnel URL appears in the banner:
#   Tunnel: https://abc123.ngrok-free.app (ngrok)

使用横幅中显示的 ngrok URL 从 Claude Chat 连接即可。就是这么简单 — 无需配置 Traefik、Caddy 或 DNS。

注意：ngrok 隧道是可选的。如果你已有反向代理（Traefik/Caddy），请保留 tunnel.enabled: false，照常使用你的域名。

server:
  host: "127.0.0.1"          # Always localhost — reverse proxy handles external
  port: 8420
  public_url: "https://herald.yourdomain.com"
  log_level: "info"           # debug, info, warn, error
  log_file: ""                # Optional file path for log output

auth:
  client_id: "herald-claude-chat"
  # client_secret is auto-generated — override with HERALD_CLIENT_SECRET env var if needed
  access_token_ttl: 1h
  refresh_token_ttl: 720h    # 30 days
  redirect_uris:
    - "https://claude.ai/oauth/callback"
    - "https://claude.ai/api/oauth/callback"
    - "https://claude.ai/api/mcp/auth_callback"

database:
  path: "~/.config/herald/herald.db"
  retention_days: 90

execution:
  claude_path: "claude"
  model: "claude-sonnet-4-5-20250929"  # Default model for tasks
  default_timeout: 30m
  max_timeout: 2h
  work_dir: "~/.config/herald/work"
  max_concurrent: 3
  max_prompt_size: 102400    # 100KB
  max_output_size: 1048576   # 1MB
  env:
    CLAUDE_CODE_ENTRYPOINT: "herald"
    CLAUDE_CODE_DISABLE_AUTO_UPDATE: "1"

projects:
  my-api:
    path: "/home/you/projects/my-api"
    description: "Main backend API"
    default: true
    allowed_tools:
      - "Read"
      - "Write"
      - "Edit"
      - "Bash(git *)"
      - "Bash(go *)"
      - "Bash(make *)"
    max_concurrent_tasks: 1
    git:
      auto_branch: true
      auto_stash: true
      auto_commit: true
      branch_prefix: "herald/"

tunnel:
  enabled: false               # Set to true to enable ngrok tunnel
  provider: "ngrok"
  authtoken: ""                # or set HERALD_NGROK_AUTHTOKEN env var
  # domain: ""                 # optional: fixed domain (paid ngrok plans)

rate_limit:
  requests_per_minute: 200
  burst: 100

MCP 工具

Herald 提供 10 个工具，Claude Chat 会通过 MCP 协议自动发现这些工具：

安全

Herald 会将 Claude Code 暴露到网络中。我们对此非常重视。

架构

Claude Chat (mobile/web)
  → HTTPS (MCP Streamable HTTP + OAuth 2.1)
  → Traefik / Caddy (TLS termination)
  → Herald (Go binary, port 8420)
    ├── MCP Handler (/mcp)
    ├── OAuth 2.1 Server (PKCE, token rotation)
    ├── Task Manager (goroutine pool, priority queue)
    ├── Executor Registry (pluggable backends, default: Claude Code)
    ├── SQLite (persistence)
    └── MCP Notifications (server push via SSE)

设计原则：单二进制文件（所有内容都编译进一个 Go 可执行文件）、异步优先（每项任务都是一个 goroutine）、无状态 MCP 搭配有状态后端、故障安全（Herald 崩溃不会终止正在运行的 Claude Code 进程）。

部署

Herald 以原生二进制文件运行效果最佳（可直接访问 Claude Code 和你的文件）。也可选择使用 Docker。

services:
  traefik:
    image: traefik:v3
    command:
      - "--entrypoints.websecure.address=:443"
      - "[email protected]"
      - "--certificatesresolvers.le.acme.storage=/letsencrypt/acme.json"
      - "--certificatesresolvers.le.acme.httpchallenge.entrypoint=web"
    ports:
      - "443:443"
    volumes:
      - "./letsencrypt:/letsencrypt"

  herald:
    build: .
    network_mode: host
    volumes:
      - "~/.config/herald:/root/.config/herald"
      - "~/projects:/root/projects:ro"
    labels:
      - "traefik.http.routers.herald.rule=Host(`herald.yourdomain.com`)"
      - "traefik.http.routers.herald.tls.certresolver=le"
      - "traefik.http.services.herald.loadbalancer.server.port=8420"

路线图

有想法？提交问题。我们会开发用户需要的功能。

参与贡献

Herald 目前处于早期 Alpha 阶段——这是参与塑造项目的最佳时机。

# Get started
git clone https://github.com/btouchard/herald.git
cd herald
make build && make test

# Create your branch
git checkout -b feat/your-feature

# Code, test, lint
make lint && make test

# Open a PR

提交消息遵循 Conventional Commits（feat:、fix:、refactor:、docs:）。

无论是修复错误、添加新的通知后端，还是改进文档，我们都欢迎各种贡献。

为什么选择 Herald？

Herald 使用的协议与 Anthropic 为其自有集成构建的协议相同。无需逆向工程、无需非官方 API，也无需担心小把戏会在下次更新时失效。

AGPL-3.0 许可证 — 由 Benjamin Touchard 构建

如果 Herald 为你节省了时间，请点个星。这有助于其他人发现这个项目。