herdr-mcp

コーディングエージェントに、実行中のHerdrターミナルセッションを制御する手段を提供するMCPサーバーです。ワークスペース、タブ、ペイン、エージェントの一覧表示、ペイン出力の読み取り、他のエージェントへのプロンプト送信、キー送信、コマンド実行、状態や出力の待機、ペインの分割・終了を行うことができます。

これは薄いstdioブリッジです。すべてのツールはherdr CLIを外部プロセスとして実行します。このCLIはすでにHerdrのソケットAPIに対応しており、JSONエンベロープで応答します。デーモンもポートも設定ファイルも認証もありません。

要件

• herdrがインストールされ、PATHに含まれていること（またはHERDR_BINにフルパスを設定すること）。

• 実行中のHerdrセッションが存在すること。サーバーは、herdr CLIが環境（HERDR_SOCKET_PATH / HERDR_SESSION）から解決するセッションと通信します。

• Python 3.12+とuv。

Related MCP server: HT MCP Server

実行

チェックアウトから:

uv run herdr-mcp

GitHubから直接（チェックアウトなし）:

uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

このプロセスはstdio経由でMCPを提供するため、stdoutには何も出力しません。ログはstderrに出力されます（argvトレースにはHERDR_MCP_LOG_LEVEL=DEBUG）。

クライアント設定

Claude Code:

claude mcp add herdr -- uvx --from git+https://github.com/aelaguiz/herdr-mcp herdr-mcp

汎用のmcpServers JSON（Claude Desktop、Cursor、Codexなど）:

{
  "mcpServers": {
    "herdr": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/aelaguiz/herdr-mcp", "herdr-mcp"],
      "env": {}
    }
  }
}

代わりにローカルチェックアウトから:

{
  "mcpServers": {
    "herdr": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/herdr-mcp", "herdr-mcp"]
    }
  }
}

ツール

ペインIDはw17:p1、タブIDはw17:t1、ワークスペースIDはw17のような形式です。エージェントツールはペインIDまたはエージェント名を受け付けます。各ツールはherdrのJSONエンベロープからパース済みのresultオブジェクトを返します。read_paneはプレーンテキストを返します。

CLIからの失敗（不明なペイン、タイムアウト、壊れたソケット）は、herdr自身のエラーコードとメッセージを伴うMCPツールエラーとして返されるため、モデルはそれ自身を修正できます。

セキュリティ

認証なし、サンドボックスなし、ローカルのstdioのみです。このサーバーを起動できるクライアントは、ターミナルペイン内で任意のコマンドを実行でき、エージェントのペインが表示しているものも含めて画面上のすべてを読み取ることができます。自分のマシン上で信頼するクライアントにのみ接続してください。

環境

環境内のその他すべては変更されずにそのまま渡されます。これによってCLIは正しいセッションのソケットを特定します。

開発

uv sync
uv run pytest -q

ユニットテストは、スタブherdrスクリプトに対してSDKのインメモリクライアントを介してサーバーを駆動するため、実際のセッションに触れることはありません。