Woodpecker CI

woodpecker-ci-mcp

軽量なコンテナネイティブCIエンジンである Woodpecker CI 用の Model Context Protocol（MCP）サーバーです。Woodpecker CIがパイプラインを実行し、このサーバーがその内容を読み取り、操作します。

Claude Code、Claude Desktop、CodexなどのMCPクライアントが、失敗したパイプラインを確認し、失敗したステップのビルドログを読み取って対処できるようにします。再起動、実行中の処理のキャンセル、ブロックされた処理の承認、シークレットのローテーション、cronの修正などが可能です。取り消せない操作は、まず担当者の確認を求めます。また、書き込みツールを完全に無効にすることもできます。

ツールは最大71個ですが、すべてを使う必要はありません。WOODPECKER_ALLOW_TOOLS=essentialを設定すると、厳選された8個だけが登録されます。モデルは71個から選ぶより、8個からのほうが適切なツールをはるかに確実に選べます。詳しくは読み込むツールの選び方をご覧ください。

違い

読み取りだけでなく、API 全体をカバーします。 リポジトリ、パイプライン、ログ、シークレット、レジストリ、cron、組織、ユーザー、エージェント、フォージ、キュー、ログレベルを扱います。Woodpecker 3.18.0 に対して 71 個のツールを提供します。CI システム向け MCP サーバーの目的は、通知された内容に対処することです。

ログはテキストで届きます。 Woodpecker はステップの出力を、行番号付きの base64 エンコードされたチャンクの配列として返します。get_step_logs はそれらをデコードして順序どおりに並べ直し、ステップの終了コードを報告し、デフォルトではログの末尾を返します。失敗したステップは最後の行で原因を説明しますが、npm ci の最初の 4000 行を見ても何も分かりません。

エージェントのトークンはモデルに渡りません。 GET /agents はすべてのエージェントのトークンを平文で返します。このトークンがあれば、マシンをサーバーに接続して、シークレットを含むパイプラインのワークロードを受け取ることができます。このサーバー経由でエージェントを一覧表示すると、トークンはマスキングされます。create_agent は引き続きトークンを返します。トークンを取得する唯一の方法であり、そのことも明記しています。

この API の注意点を把握しています。 /version と /healthz は、Swagger ドキュメントで指定されている /api プレフィックスの外側にあります。そのため、GET /api/version は 404 ではなく HTTP 200 で Web UI を返します（3.19 ではこれらが /api 配下に追加され、4.0 ではルートのルートが削除されるため、get_server_info はプレフィックスにフォールバックします）。フォージに存在するリポジトリも、有効化されるまではここでは 404 になります。perPage が 50 を超えると、何も通知されずに上限が適用されます。cron のスケジュールは 6 フィールドではなく 5 フィールドです。また、イベントリストのないシークレットは拒否されます。期待されるデフォルト値は API ではなく Web UI にあるためです。

要件

• Node.js ≥ 22
• Woodpecker の個人用アクセストークン — ユーザー設定の「CLI and API」にあります。 スコープはありません。このトークンはアカウントの全権限を持ちます。

設定

変数	必須	説明
WOODPECKER_URL	はい	サーバーのルート URL。例：https://woodpecker.example.com
WOODPECKER_TOKEN	はい	ユーザー設定から取得した個人アクセストークン
WOODPECKER_READ_ONLY	いいえ	true の場合、読み取り専用ツール 34 個のみを登録します
WOODPECKER_ALLOW_TOOLS	いいえ	カンマ区切りのツール名、list_* プレフィックス、または厳選プリセットの essential
WOODPECKER_DENY_TOOLS	いいえ	同じ構文です。WOODPECKER_ALLOW_TOOLS によって残ったツールから除外されます
WOODPECKER_INSECURE_TLS	いいえ	true の場合、自己署名証明書を許可します（この接続にのみ適用）
WOODPECKER_API_PREFIX	いいえ	ルート以下の API パス。既定値は /api。Crow CI 5 以降では /api/v1
ELICITATION	いいえ	false の場合、承認ダイアログを 2 回呼び出すトークンに置き換えます。プレフィックスは付きません

WOODPECKER_URL は API のルートではなく、サーバーのルートです。 https://woodpecker.example.com を指定し、https://woodpecker.example.com/api は指定しないでください。Swagger ページではすべての例が長い形式で記載されているため、どちらも受け付けます。サフィックスは取り除かれます。

Crow CI は Woodpecker のフォークで、5.0 以降は /api/v1 以下で API を提供します。WOODPECKER_API_PREFIX=/api/v1 を設定してください。これにより API にアクセスできるようになりますが、完全に同一ではありません。このサーバーは Woodpecker 3 API を使用し、Crow はそのフィールドの一部を無視します。Crow CI を参照してください。

https:// を使用してください。 通常の http ではトークンが暗号化されずに送信されます。ホストがローカルでない限り、サーバーは警告を表示します。自己署名証明書を使う場合は、WOODPECKER_INSECURE_TLS よりも適切な内部 CA を使用してください。

設定がなくてもサーバーは起動し、ツールを一覧表示します（そのため、レジストリやインスペクターから内容を確認できます）。ただし、すべての呼び出しは API にアクセスせず、セットアップ手順を示して失敗します。get_server_info はトークンなしで動作するため、ほかの機能が動かないときに最初に呼び出すツールとして適しています。応答があれば、WOODPECKER_URL は正しく、問題はトークンにあります。

管理者専用ツール。 Woodpecker はリポジトリと組織の権限をフォージから引き継ぎ、ユーザー、エージェント、フォージ、キュー、ログレベルの管理をインスタンス管理者に限定しています。これらのツールはすべてのユーザーに登録されますが、使用権限のないアカウントには 403 を返します。get_current_user ではトークンが属するアカウントの種類を確認できます。また、これらのツールを一切提示しないようにするには、WOODPECKER_DENY_TOOLS を設定するのが簡単です。

読み込むツールの選択

WOODPECKER_ALLOW_TOOLS と WOODPECKER_DENY_TOOLS は、カンマ区切りのツール名を受け取ります。末尾の * はファミリー全体に一致します。essential は厳選されたプリセットで、list_repositories、get_repository、list_pipelines、get_pipeline、get_step_logs、trigger_pipeline、restart_pipeline、cancel_pipeline が含まれます。これらは ツールリファレンスでそのように示されています。

WOODPECKER_ALLOW_TOOLS=essential
WOODPECKER_ALLOW_TOOLS=list_*,get_pipeline,get_step_logs
WOODPECKER_DENY_TOOLS=delete_*,pause_queue,create_user,update_user

ツールが71個もある場合、これは単なる気配りではありません。表示されるツールは、リクエストのたびにコンテキストを消費します。また、delete_forge を get_step_logs と並べて提供するサーバーを、事前に対象を絞り込まずに本番の CI に接続すべきではありません。

どのツールにも一致しないエントリがあると、名前を示して起動が中止されるため、入力ミスによってツールが気付かれずに隠れることはありません。存在しないツールを環境変数のせいだと突き止める人はいないでしょう。フィルタリングされたツールは登録されないため、tools/list にも tools/call にも現れず、WOODPECKER_READ_ONLY のもとで書き込みツールが使えないのと同じです。

これらのサーバーを複数同時に実行する場合は、もうひとつの選択肢として mcp-hub があります。その /hub エンドポイントは、すべてのサーバーのツールを6つのメタツールに置き換えます。

インストール

Claude Code

claude mcp add woodpecker-ci -- npx -y @ni-c/woodpecker-ci-mcp

Claude Desktop

{
  "mcpServers": {
    "woodpecker-ci": {
      "command": "npx",
      "args": ["-y", "@ni-c/woodpecker-ci-mcp"],
      "env": {
        "WOODPECKER_URL": "https://woodpecker.example.com",
        "WOODPECKER_TOKEN": "…"
      }
    }
  }
}

Codex

[mcp_servers.woodpecker-ci]
command = "npx"
args = ["-y", "@ni-c/woodpecker-ci-mcp"]
env = { WOODPECKER_URL = "https://woodpecker.example.com", WOODPECKER_TOKEN = "…" }

Docker

docker run --rm -i \
  -e WOODPECKER_URL=https://woodpecker.example.com \
  -e WOODPECKER_TOKEN=… \
  ghcr.io/ni-c/woodpecker-ci-mcp

Woodpecker がホストのスプリット DNS 経由でしか名前解決できない場合は、--dns <resolver> を追加してください。コンテナはホストのリゾルバー設定を引き継ぎません。また、内部名に対するパブリック DNS の応答は、通常、応答しないアドレスです。

mcp-hub 経由

ローカルプロセスを起動できないクライアント（ChatGPT コネクター、Web 版 Claude、Cursor、LibreChat）は、mcp-hub 経由で woodpecker-ci-mcp に接続します。1つのコンテナで複数の stdio MCP サーバーを Streamable HTTP 経由で提供し、単一のパスワードの背後に OAuth 2.1 ログインを用意します。また、OAuth に対応できないクライアント向けに長期間有効なトークンも提供します。/hub エンドポイントはすべてのサーバーを6つのメタツールの背後に配置するため、モデルのコンテキストに N×個のツールスキーマを含めずに、1つのコネクターからすべてのサーバーに接続できます。また、どちらのプロトコルリビジョンにも対応しています。このサーバーが尋ねる質問は、これを経由して向こう側の人に届きます。

/config/mcp.json は Claude Code の形式を使うため、すでに設定済みのエントリをそのまま使用できます。

{
  "mcpServers": {
    "woodpecker-ci": {
      "command": "npx",
      "args": ["-y", "@ni-c/woodpecker-ci-mcp"],
      "env": {
        "WOODPECKER_URL": "https://woodpecker.example.com",
        "WOODPECKER_TOKEN": "…"
      }
    }
  }
}

ここでの allowTools と denyTools は、ハブ独自のサーバーごとのフィルターであり、env 内の *_ALLOW_TOOLS と同じものではありません。その違いと、起こり得る間違いについては、クライアントガイドを参照してください。

ツール

読み取りツールは常に登録されています。🛡はインスタンス管理者が必要なツール、👤はMCPエリシテーションを通じて実行前に人に確認するツールを示します。クライアントがダイアログを表示できない場合は、2回の呼び出しによるconfirm_tokenにフォールバックします。

すべてのツールはoutputSchemaを宣言し、テキストブロックに加えてstructuredContentも返すため、クライアントは文章を解析せずに結果を利用できます。「Pipeline 12 was cancelled.」のような一文で応答していた17個のツールは、現在、フィールドも返すようになりました。一文は読み手が必要とする場所にそのまま残ります。get_step_logsは、レンダリングされたヘッダーとログをテキストに残し、終了コード、行数、出力をフィールドとして示します。

プッシュされたコンテンツを報告するツールは、フィールドにuntrusted: trueとsource: "woodpecker"を含みます。ブランチ名、コミットメッセージ、パイプラインのタイトル、そして何より任意のコンテナーの生の標準出力であるビルドログは、プッシュ権限を持つユーザーなら誰でも書き込めます。この一覧は呼び出し箇所に従っており、ツールは、応答がすでに信頼できないデータ用のラッパーを経由している場合に限り、マークされています。

Woodpeckerのオブジェクトは、このサーバーが構築するトップレベルのキーを持つオープンオブジェクトとして記述されています。アップストリームのGoモデルはリリースごとにシリアライズする内容が変わり、SDKは各結果が外部に出る前にスキーマに照らして検証します。厳密な構造にすると、あるリリースで追加されたフィールドによってツール全体が失敗することになります。 パラメーターについてはツールリファレンスをご覧ください。

リポジトリ

ツール	説明
list_repositories	リポジトリの一覧。必要に応じて、まだ有効化されていないものも含めます
get_repository	Woodpeckerの設定をすべて含む、1つのリポジトリ
lookup_repository	owner/nameを、他のすべてのツールが受け取るIDに変換します
get_repository_permissions	このアカウントがここで実行できる操作。「なぜ403なのか」に答えます
list_repository_branches	フォージ上でWoodpeckerが認識しているブランチ
list_pull_requests	オープンなプルリクエストとそのインデックス
activate_repository	フォージのリポジトリでWoodpeckerを有効にします
update_repository 👤	設定ファイル、タイムアウト、公開範囲、承認モード。信頼を付与するには👤
repair_repository 👤	Webhookを再インストールします。インスタンス全体を対象にする場合のみ👤
move_repository 👤	フォージ上で移動したリポジトリを追跡します
chown_repository 👤	所有権を移し、Woodpeckerが使用するトークンを自分のものにします
delete_repository 👤	履歴も含めてWoodpeckerから削除します

パイプラインとログ

ツール	説明
list_pipelines	ブランチ、イベント、ステータス、時間で絞り込んだパイプライン
get_pipeline	ワークフロー、ステップ、ステップ ID を含む単一のパイプライン
get_pipeline_config	この実行の元になった YAML
get_pipeline_metadata	ステップが認識した CI_* 環境と前回の実行
list_queued_pipelines	すべてのリポジトリで待機中の項目
get_step_logs	ステップの出力（テキスト）。末尾から表示し、終了コードも含む
trigger_pipeline	ブランチでパイプラインを開始
restart_pipeline	既存のパイプラインを同じコミットで再実行
cancel_pipeline	保留中または実行中のパイプラインを停止
approve_pipeline 👤	ブロックされたパイプラインを承認 — シークレットを使ってフォークのコードを実行します
decline_pipeline	ブロックされたパイプラインを拒否
delete_pipeline 👤	パイプラインとそのログを削除
delete_step_logs 👤	1 つのステップの出力を削除 — ステップがシークレットを出力した場合に使用
delete_pipeline_logs	👤 パイプラインのすべてのステップで同様の操作

シークレット、レジストリ、cron

scope はレベルを選択します：repository、organization、global。

ツール	説明
list_secrets	1 つのレベルにあるシークレット。値が Woodpecker から返されることはありません
get_secret	1 つのシークレットのイベント、イメージ、メモ
create_secret	シークレットを作成します。イベントが 1 つ以上必要です
update_secret 👤	値をローテーションする（👤）か、イベントとイメージのリストを置き換えます
delete_secret 👤	シークレットを削除します。これを使用するパイプラインは、シークレットなしで実行されます
list_registries	1 つのレベルにあるコンテナレジストリの認証情報
get_registry	1 つのエントリ。パスワードは Woodpecker によって除外されます
create_registry	プライベートイメージをプルするための認証情報を保存します
update_registry	ユーザー名またはパスワードを変更します
delete_registry 👤	レジストリを削除します
list_crons	スケジュールされた実行と、次回の実行時刻
get_cron	1 つの cron ジョブ
create_cron	実行をスケジュールします — 5 フィールドの cron または @daily
update_cron	enabled を含めて変更します。削除せずに一時停止できます
run_cron	スケジュールに触れずに、今すぐ実行します
delete_cron 👤	スケジュールを削除します

アカウント、組織、インスタンスの管理

ツール	説明
get_current_user	トークンが属するアカウントと、管理者かどうか
get_pipeline_feed	表示可能な各リポジトリの最新パイプラインを、1 回の呼び出しで取得
list_organizations 🛡	インスタンスが認識している組織
get_organization	1 つの組織
lookup_organization	名前を、組織レベルのツールが必要とする ID に変換
get_organization_permissions	このアカウントのメンバー権限と管理者権限のフラグ
delete_organization 🛡👤	組織レベルのシークレット、レジストリ、エージェントとともに削除
list_users 🛡	これまでにログインしたことのあるアカウント
get_user 🛡	1 つのアカウント — forge_id が必要
create_user 🛡👤	レコードを事前作成します。管理者権限を付与する場合のみ 👤
update_user 🛡👤	メールアドレスを変更します。管理者権限の付与には 👤
delete_user 🛡👤	アカウントを削除します — 先にリポジトリを移管してください
list_agents 🛡	ビルドエージェント。トークンは伏せられます
get_agent 🛡	1 つのエージェント。トークンは伏せられます
list_agent_tasks 🛡	エージェントが現在実行中の内容
create_agent 🛡	エージェントを登録し、そのトークンを返します — 認証情報です
update_agent 🛡	no_schedule を使って名前やラベルを変更したり、処理を停止したりします
delete_agent 🛡👤	エージェントを削除し、トークンを無効化します
list_forges 🛡	このインスタンスが認証に使用する Forge
get_forge 🛡	1 つの Forge。OAuth シークレットは返されません
create_forge 🛡👤	Forge を追加します — サインイン方法の追加なので、先に確認を求めます
update_forge 🛡👤	Forge を変更します — 誤った値を設定すると、全員が締め出されます
delete_forge 🛡👤	Forge を削除します
get_server_info	バージョンと稼働状態。トークンなしで動作します
get_queue_info 🛡	サーバー側のキューとエージェントの統計
get_log_level 🛡	現在のサーバーログレベル
pause_queue 🛡👤	インスタンス全体のスケジューリングを停止します
resume_queue 🛡	スケジューリングを再開します
set_log_level 🛡👤	ログレベルを変更します。サーバーのログを抑制するには 👤

意図的に公開していない機能

• POST/DELETE /user/token。 このサーバーが認証に使っているアカウントの個人用アクセストークンを返し、ローテーションします。モデルに自分自身の認証情報を渡すツールは機能ではなく、セッション中にサーバー自身の設定を無効にするツールはさらに厄介です。Web UI では、人が操作する前提でこの両方を行えます。
• POST /hook。 Forge の Webhook エンドポイントです。これを呼び出すことは、push イベントを偽装することを意味します。誰かが何かをコミットしたように見せかけてパイプラインを実行する手段です。trigger_pipeline が正規の方法です。
• /debug/pprof/*。 Go のプロファイリングデータを返す 9 つのエンドポイントです。ヒープダンプをモデルのコンテキストに入れるべきではありません。
• /stream/events と /stream/logs。 サーバー送信イベントのストリームは、リクエスト／レスポンス型のツールには適しません。代わりに get_pipeline をポーリングしてください。
• バッジのエンドポイント。 埋め込み用の SVG と XML を返すもので、情報を返すものではありません。

安全性

• 24 個の操作では人の承認を求めます。 すべての delete_* に加え、move_repository、chown_repository、インスタンス全体を対象とする repair_repository、create_forge、update_forge、pause_queue、approve_pipeline が対象です。さらに、権限を強める方向でのみ対象となる操作が 6 つあります。update_user で admin を付与する場合、create_user で admin ユーザーを作成する場合、update_repository で trusted_* フラグを付与する場合、またはフォークの制限を緩和する場合（require_approval を無効にする、visibility を public にする）、update_secret で値を上書きする場合、または読み取り可能な対象を広げる場合、update_registry でパスワードを置き換える場合、set_log_level でサーバーのログ出力を抑止する場合です。

  クライアントが MCP のエリシテーションに対応している場合、モデルが人に代わって応答できない実際のダイアログが表示されます。対応していない場合は、最初の呼び出しで、その引数の組み合わせに紐付けられた短時間有効なトークンが返され、それを含めた 2 回目の呼び出しで初めて操作が実行されます。これにより、同じ引数で呼び出しが 2 回行われたことだけが証明されます。表示される文面でも、そのことを明記しています。いずれの場合も、あるリポジトリに対する承認が別のリポジトリに対する承認になることはなく、あるツールへの承認が別のツールへの承認になることもありません。ELICITATION=false にすると意図的にフォールバックが使われますが、ガードが取り除かれることはありません。人に承認を求めるを参照してください。

• エージェントトークンは読み取り時に伏字になります。上記を参照してください。必要上、create_agent は例外です。

• シークレットの値とレジストリのパスワードは返されません。このサーバーが隠しているからではありません。Woodpecker が、作成直後のレスポンスも含め、すべてのレスポンスからそれらを除去します。値は別の場所にも保存してください。

• ビルドログ、コミットメッセージ、パイプラインのメタデータは信頼できないデータとして扱われます。リポジトリに push できる人なら誰でもそれらを書き込めるためです。確認プロンプトでは、API 由来の内容を引用しません。

• エラーボディは切り詰められ、HTML のエラーページは破棄されます。また、すべてのレスポンスはストリーミング中にバイト数の上限が適用されます。ログ出力にはさらに小さな独自の上限があり、切り詰められた場合はその旨が示されます。

• WOODPECKER_READ_ONLY=true にすると書き込みツールは登録されません。WOODPECKER_DENY_TOOLS では同じ仕組みで、さらに細かく制限できます。除外されたツールは構築されないため、呼び出し時に拒否されることはありません。

• トークンは読み取り後に process.env から削除され、リダイレクト先に送信されることも、エラーメッセージに出力されることもありません。

ドキュメント

完全なガイド、ツールリファレンス、安全性に関する注意事項は woodpecker-ci-mcp.ni-c.de（ソースは docs/）にあります。

開発

npm install
npm run lint && npm run build && npm run test:coverage

リリース

1. CHANGELOG の項目を追加し、package.json のバージョンを更新します。
2. npm run lint && npm run build && npm run test:coverage
3. コミットしてから、署名付きタグを push します：git tag -s vX.Y.Z -m "vX.Y.Z" && git push origin main vX.Y.Z

リリースワークフローでは npm に公開し（Trusted Publishing、provenance 付き）、CHANGELOG の項目から GitHub リリースを作成し、MCP Registry のエントリーを更新します。

コントリビューション

Issue、ディスカッション、プルリクエストを歓迎します。CONTRIBUTING.mdをご覧ください。脆弱性については、公開 Issue ではなく 非公開での報告をご利用ください。ポリシーはSECURITY.mdに記載されています。

ライセンス

MIT © Willi Thiel