Herald

io.github.btouchard由 GitHub 账号 btouchard 发布v1.0.0更新于 Oct 25, 2026

Stop copy-pasting between Claude Chat and Claude Code.

已验证Streamable HTTP可网页运行效率与工作流开发者工具

概览

AI 生成的概览

Herald 是自托管的 MCP 桥接服务，让 Claude Chat 把编码任务派发到本机的 Claude Code，并远程查看结果。

可以做什么
启动、查看、取消和列出 Claude Code 任务，支持优先级、超时、会话续接和 Git 分支选项，并取回完整结果或 JSON 输出。查看任务的 Git 差异，列出已配置项目及其 Git 状态。在项目范围内读取文件，并带有路径穿越防护。把 Claude Code 会话推送到 Herald，以便在其他设备上监控和继续。查看日志与活动历史，任务更新会以通知形式推送到对话中。
适用场景
适合想通过 Claude Chat 在手机或浏览器上启动并跟踪本机 Claude Code 工作、避免在两者之间复制粘贴的场景，也适合希望每个任务在独立 Git 分支上隔离执行的情况。
运行要求
需要一个可通过 HTTPS 访问的自托管 Herald 实例，可用反向代理或内置 ngrok 隧道（需 ngrok 认证令牌，可通过 HERALD_NGROK_AUTHTOKEN 提供）。主机需安装 Claude Code CLI，并准备列出项目和允许工具的 YAML 配置；Claude Chat 端通过 OAuth 2.1 认证，客户端密钥自动生成，可用 HERALD_CLIENT_SECRET 覆盖。
安装前请注意
Herald 会把 Claude Code 和文件系统暴露到网络，持有有效令牌的人可以启动任务，在已配置项目中读取、写入、执行命令并提交。请按项目限制 allowed_tools，并妥善保管 OAuth 凭据和 ngrok 令牌。任务会创建分支；若启用 auto_commit 或 auto_stash，还会提交或暂存改动；cancel_task 可回滚 Git 变更。任务提示和结果保存在本地 SQLite 数据库中。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Herald，将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Web executable，通过 Streamable HTTP。 远程服务在工作区中配置后即可从网页运行时运行。

交给智能体安装

把这段提示词粘贴到 Claude Code、Codex、Cursor 等智能体，或 SourceWeft 对话中。智能体会读取该服务器的安装指南，先向你展示发布者、端点和登录方式，经你同意后再把它添加到你的客户端。密钥不会写进任何命令。

阅读 https://sourceweft.com/mcp/io.github.btouchard%2Fherald/install.md，并按其中说明把这个 MCP 服务器接入我的客户端。修改任何配置之前，先告诉我它的发布者、端点和登录方式，等我确认。不要把 API 密钥写进命令或我会提交的文件；问我密钥应从哪里获取。

查看智能体所依据的安装指南

其他 MCP 客户端

把它添加到你客户端的 mcpServers 配置中。

{
  "mcpServers": {
    "herald": {
      "type": "http",
      "url": "https://your-herald-instance.example.com/mcp"
    }
  }
}

README

Herald

Code from your phone. Seriously.
The self-hosted MCP bridge between Claude Chat and Claude Code.

[Go 1.26+] [AGPL-3.0 License] [GitHub Stars]

Documentation · Quick Start · How It Works · Features · Security · Roadmap
🇫🇷 Version française

[图片]

You're on the couch. On your phone. You open Claude Chat and type:

"Refactor the auth middleware in my-api to use JWT instead of session cookies. Run the tests."

Four minutes later, it's done. Branch created, code refactored, tests passing, changes committed. Your workstation did all the work. You never opened your laptop.

That's Herald.

The Problem

Claude Chat and Claude Code are two brilliant tools that live in completely separate worlds.

Claude ChatClaude Code
WhereBrowser, phone, anywhereYour terminal
WhatConversations, analysis, thinkingReads, writes, and ships actual code
GapCan't touch your codebaseCan't leave your desk

You've been copy-pasting between them. Or worse — you've been waiting until you're back at your desk. That's over.

The Solution

Herald is a self-hosted MCP server that bridges Claude Chat to Claude Code using Anthropic's official Custom Connectors protocol. One Go binary. Zero hacks.

  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

The bridge is bidirectional. Claude Chat dispatches tasks to Claude Code, and Claude Code can push session context back to Herald for remote monitoring and continuation from another device.

Your code never leaves your machine. Herald just orchestrates.

How It Works

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(...)

Three tools. That's the core loop. Start, check, get results — all from wherever you are.

Reverse flow: Claude Code → Herald

Working in your terminal and want to continue from your phone? Claude Code pushes its session to 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

Features

Core

  • Native MCP bridge — Uses Anthropic's official Custom Connectors protocol. Not a hack, not a wrapper, not a proxy.
  • Async task execution — Start tasks, check progress, get results. Claude Code runs in the background while you do other things.
  • Git branch isolation — Each task runs on its own branch. Your main branch stays untouched.
  • Session resumption — Multi-turn Claude Code conversations. Pick up where you left off.
  • Bidirectional bridge — Claude Code can push session context to Herald via herald_push for remote monitoring and continuation from another device.

Multi-Project

  • Multiple projects — Configure as many projects as you need, each with its own settings.
  • Per-project tool restrictions — Control exactly which tools Claude Code can use. Full sandboxing per project.

Operations

  • MCP push notifications — Herald pushes task updates directly to Claude Chat via MCP server notifications. No polling needed.
  • SQLite persistence — Tasks survive server restarts. Full history, fully searchable.

Engineering

  • Single binary — One Go executable, ~15MB. No Docker, no runtime, no node_modules.
  • Zero CGO — Pure Go. Cross-compiles to Linux, macOS, Windows, ARM.
  • 6 dependencies — chi, mcp-go, modernc/sqlite, uuid, yaml, testify. That's the entire dependency tree.

Quick Start

Prerequisites: Claude Code CLI installed, HTTPS via ngrok (built-in) or a domain with reverse proxy.

1. Install

bash
curl -fsSL https://raw.githubusercontent.com/btouchard/herald/main/install.sh | sh
Or build from source (requires Go 1.26+)
bash
git clone https://github.com/btouchard/herald.gitcd herald && make build# Binary is in ./bin/herald

2. Configure

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

3. Run

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

Edit ~/.config/herald/herald.yaml with your domain and projects:

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/"

Then connect from Claude Chat:

  1. Claude Chat → Settings → Custom Connectors
  2. Add connector: https://herald.yourdomain.com/mcp
  3. Authenticate via OAuth
  4. Done — Claude Chat now has 10 new tools to control your workstation

Quick Start with ngrok (No Reverse Proxy Needed)

Don't have a domain or reverse proxy? Use ngrok to expose Herald instantly over HTTPS:

1. Get ngrok auth token

Sign up at ngrok.com (free plan works) and grab your auth token from the dashboard.

2. Enable tunnel in config

Edit ~/.config/herald/herald.yaml:

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. Run Herald

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

Connect from Claude Chat using the ngrok URL shown in the banner. That's it — no Traefik, Caddy, or DNS setup required.

Note: The ngrok tunnel is optional. If you already have a reverse proxy (Traefik/Caddy), leave tunnel.enabled: false and use your domain as usual.

Full configuration reference
yaml
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 Tools

Herald exposes 10 tools that Claude Chat discovers automatically via the MCP protocol:

ToolWhat it does
start_taskLaunch a Claude Code task. Returns an ID immediately. Supports priority, timeout, session resumption, and Git branch options.
check_taskCheck status and progress. Optionally include recent output.
get_resultGet the full result of a completed task (summary, full, or json).
list_tasksList tasks with filters — status, project, time range.
cancel_taskCancel a running or queued task. Optionally revert Git changes.
get_diffGit diff for a task's branch or uncommitted changes.
list_projectsList configured projects with Git status.
read_fileRead a file from a project (path-safe — cannot escape project root).
herald_pushPush a Claude Code session to Herald for remote monitoring and continuation from another device.
get_logsView logs and activity history.

Security

Herald exposes Claude Code to the network. We take that seriously.

LayerProtection
NetworkBinds to 127.0.0.1 only. HTTPS via built-in ngrok tunnel or reverse proxy (Traefik/Caddy).
AuthOAuth 2.1 with PKCE. Every request needs a valid Bearer token.
TokensAccess tokens: 1h. Refresh tokens: 30d, rotated on each use.
FilesystemPath traversal protection on all file operations. Symlink escapes blocked.
ExecutionPer-project tool restrictions. No blanket --dangerously-skip-permissions.
Rate limiting200 req/min per token (configurable).
TimeoutsEvery task has a deadline (default: 30min). No runaway processes.
PromptsPassed to Claude Code unmodified. No injection, no enrichment, no rewriting.
AuditEvery action logged with timestamp and identity.

Architecture

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)

Design principles: single binary (everything compiled into one Go executable), async-first (each task is a goroutine), stateless MCP with stateful backend, fail-safe (Herald crash doesn't kill running Claude Code processes).

Tech stack
ComponentChoiceWhy
LanguageGo 1.26Single binary, cross-compilation, goroutines
MCPmcp-goStreamable HTTP, official protocol support
RouterchiLightweight, stdlib-compatible
Databasemodernc.org/sqlitePure Go, zero CGO
Logginglog/slogGo stdlib, structured
Configgopkg.in/yaml.v3Standard YAML

6 direct dependencies. No ORM. No logging framework. No build toolchain.

Deployment

Herald runs best as a native binary (direct access to Claude Code and your files). Docker is available as an option.

Docker Compose with Traefik
yaml
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"

Roadmap

VersionStatusFocus
v0.1✅ DoneCore MCP server, async tasks, Git integration, OAuth 2.1, SQLite
v0.2🚧 In progressShared memory — bidirectional context between Claude Chat and Claude Code
v0.3🚀 FutureStable API, plugin system

Have an idea? Open an issue. We build what users need.

Contributing

Herald is in early alpha — the best time to shape a project.

bash
# Get startedgit clone https://github.com/btouchard/herald.gitcd heraldmake build && make test
# Create your branchgit checkout -b feat/your-feature
# Code, test, lintmake lint && make test
# Open a PR

Commit messages follow Conventional Commits (feat:, fix:, refactor:, docs:).

Whether it's a bug fix, a new notification backend, or a documentation improvement — all contributions are welcome.

Why Herald?

HeraldCopy-paste workflowOther tools
Official protocolMCP Custom ConnectorsN/ACustom APIs, fragile
Your code stays localAlwaysYesDepends
Works from phoneNativeNoRarely
Self-hosted100%N/AOften SaaS
Dependencies6N/A50-200+
Setup time~5 minutesN/A30min+
CGO requiredNoN/AOften

Herald uses the same protocol Anthropic built for their own integrations. No reverse engineering, no unofficial APIs, no hacks that break on the next update.

AGPL-3.0 License — Built by Benjamin Touchard

If Herald saves you time, leave a star. It helps others find the project.

来源：README.md，提交 5e9982e

工具

0
SourceWeft 尚未读取此服务器的工具。

版本历史

1
  1. v1.0.0最新Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度，依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价，也不表示服务器安全或当前可用：可连通性是带日期的检查结果，评分也不包含安装量或用户评价。

  • 近 30 天内可连通必需25 分

    请保持端点能够响应 MCP 握手；SourceWeft 每 30 天探测一次。

  • 已声明认证方式必需10 分

    请在注册中心条目中声明凭据请求头，或保持端点能够响应探测，以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list，或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分