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

Herald

スマートフォンからコードを書きましょう。本当です。
Claude Chat と Claude Code をつなぐ、セルフホスト可能な MCP ブリッジ。

ドキュメント · クイックスタート · 仕組み · 機能 · セキュリティ · ロードマップ
🇫🇷 フランス語版

ソファでくつろぎながら、スマートフォンを使っています。Claude Chat を開いて、次のように入力します。

「my-api の認証ミドルウェアをリファクタリングして、セッション Cookie の代わりに JWT を使うようにしてください。テストも実行してください。」

4 分後、作業は完了です。ブランチが作成され、コードがリファクタリングされ、テストが成功し、変更がコミットされています。すべての作業はワークステーションが行いました。ノートパソコンを開く必要はありませんでした。

それが Herald です。

問題

Claude Chat と Claude Code は、完全に別々の世界で動作する、どちらも優れたツールです。

これまでは両者の間でコピー＆ペーストを繰り返していました。あるいはもっと悪いことに、デスクに戻るまで待っていました。もうその必要はありません。

解決策

Herald は、Anthropic 公式のカスタムコネクタープロトコルを使って、Claude Chat と Claude Code をつなぐセルフホスト可能な MCP サーバーです。Go のバイナリ 1 つ。ハックは一切ありません。

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

ツールは 3 つ。それが基本の流れです。どこにいても、タスクを開始し、状況を確認し、結果を受け取れます。

逆方向のフロー：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 公式のカスタムコネクタープロトコルを使用します。ハックでも、ラッパーでも、プロキシでもありません。
• 非同期タスク実行 — タスクを開始し、進捗を確認して、結果を受け取れます。ほかの作業をしている間、Claude Code はバックグラウンドで実行されます。
• Git ブランチの分離 — 各タスクは独自のブランチで実行されます。メインブランチには影響しません。
• セッションの再開 — Claude Code との複数ターンの会話に対応します。前回の続きから作業できます。
• 双方向ブリッジ — Claude Code は herald_push 経由でセッションのコンテキストを Herald にプッシュし、リモートでの監視や別のデバイスからの続行に利用できます。

複数プロジェクト

• 複数プロジェクト — 必要な数のプロジェクトを、それぞれ独自の設定で構成できます。
• プロジェクトごとのツール制限 — Claude Code が使用できるツールを厳密に制御できます。プロジェクトごとに完全なサンドボックス化を実現します。

運用

• MCP プッシュ通知 — Herald は MCP サーバーの通知を通じて、タスクの更新を Claude Chat に直接プッシュします。ポーリングは不要です。
• SQLite による永続化 — サーバーを再起動してもタスクは保持されます。すべての履歴を保存し、検索できます。

エンジニアリング

• 単一バイナリ — Go の実行ファイルは 1 つだけで、サイズは約 15MB です。Docker、ランタイム、node_modules は不要です。
• CGO ゼロ — 純粋な Go です。Linux、macOS、Windows、ARM 向けにクロスコンパイルできます。
• 依存関係は 6 つ — chi、mcp-go、modernc/sqlite、uuid、yaml、testify です。依存関係ツリーはこれだけです。

クイックスタート

前提条件：Claude Code CLI がインストールされていること。HTTPS 接続には ngrok（組み込み）またはリバースプロキシ付きのドメインを使用します。

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 を使えば、Herald を HTTPS 経由ですぐに公開できます。

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)

設計原則：単一バイナリ（すべてを1つのGo実行ファイルにコンパイル）、非同期優先（各タスクはゴルーチンで実行）、ステートレスな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"

ロードマップ

アイデアがありますか？Issueを作成してください。ユーザーが必要とするものを作ります。

コントリビューション

Heraldはまだ初期アルファ版です。プロジェクトの方向性を形作るには最適な時期です。

# 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が時間の節約に役立ったら、スターを付けてください