Forgejo MCP Server

Forgejo MCP サーバー

📦 このプロジェクトは移転しました。 開発、課題、リリース、コンテナーイメージはすべて、 https://git.b4mad.industries/agentic-forges/forgejo-mcp に移りました。 Codeberg の codeberg.org/goern/forgejo-mcp リポジトリは読み取り専用ミラーとしてのみ残っており、コンテナーレジストリからイメージは公開されなくなりました。今後は git.b4mad.industries/agentic-forges/forgejo-mcp からプルしてください。課題番号は移転後も維持されています。新しい場所では、人間と AI エージェントのどちらからの貢献も歓迎します。

git clone https://git.b4mad.industries/agentic-forges/forgejo-mcp.git

forgejo.b4mad.net を指すリモートやブックマークがある場合、これは以前の名前で運用されていた同じフォージです。2026-07-29 に改名されましたが、再度移転したわけではありません。旧名でも引き続き名前解決でき、同じホストキーでポート 2222 を提供するため、既存のクローンも引き続き動作します。都合のよいときに接続先を変更してください。

git remote set-url origin \
  ssh://[email protected]:2222/agentic-forges/forgejo-mcp.git
ssh-keyscan -p 2222 git.b4mad.industries >> ~/.ssh/known_hosts

AI アシスタントを Forgejo リポジトリに接続します。自然言語を使って、課題、プルリクエスト、ファイルなどを管理できます。

このツールでできること

Forgejo MCP サーバーは、Forgejo と Model Context Protocol (MCP) システムを接続する統合プラグインです。設定すると、Claude、Cursor、VS Code 拡張機能など、MCP 対応の AI アシスタントから Forgejo リポジトリを操作できます。

使用できるコマンドの例：

• 「自分のリポジトリをすべて一覧表示して」
• 「タイトルが『Bug in login page』の課題を作成して」
• 「my-org/my-repo のオープンなプルリクエストを表示して」
• 「main ブランチの README.md の内容を取得して」
• 「agentic-forges/forgejo-mcp の最新の Actions ワークフロー実行を表示して」

クイックスタート

1. インストール

オプション A：Go を使用（推奨）

git clone https://git.b4mad.industries/agentic-forges/forgejo-mcp.git
cd forgejo-mcp
go install .

$GOPATH/bin（通常は ~/go/bin）が PATH に含まれていることを確認してください。

注： クローンせずに、モジュールパスから直接インストールすることもできます。

go install git.b4mad.industries/agentic-forges/forgejo-mcp/v3@latest

オプション B：バイナリをダウンロード

最新リリースをリリースページからダウンロードしてください。

Arch Linux では、お好みの AUR ヘルパーを使用してください。

yay -S forgejo-mcp      # builds from source
yay -S forgejo-mcp-bin  # uses pre-built binary

オプション C：Nix / NixOS

Nix パッケージマネージャーを使用して、サーバーを直接実行できます。

nix-shell -p forgejo-mcp

Flakes を使用する場合：

nix run nixpkgs#forgejo-mcp

注： forgejo-mcp は現在 unstable チャンネルでのみ利用でき、25.11 安定版リリースにはまだ含まれていません。

オプション D：コンテナーイメージ

署名済みのマルチステージ OCI イメージが、各リリースで git.b4mad.industries/agentic-forges/forgejo-mcp に公開されます。ソースからビルドせずにサーバーを実行できます。

# Latest release
podman run --rm -i \
  -e FORGEJO_ACCESS_TOKEN="<your personal access token>" \
  git.b4mad.industries/agentic-forges/forgejo-mcp:latest \
  --transport stdio --url https://your-forgejo-instance.org

# Or pin a specific version
podman run --rm -i git.b4mad.industries/agentic-forges/forgejo-mcp:v3.1.0 --help

タグ	意味
vMAJOR.MINOR.PATCH	不変 — 正確なリリース（例：v3.1.0）。本番環境で使用してください。
latest	変動 — 最新リリースを指します。利便性のためのタグです。

イメージは単一アーキテクチャ（linux/amd64）で、cosign で署名され、CycloneDX SBOM が添付されています。実行前に署名と来歴を確認するには、コンテナーイメージの検証を参照してください。

2. アクセストークンを取得

1. Forgejo インスタンスにログインします
2. Settings → Applications → Access Tokens に移動します
3. 必要な権限（repo、issue など）を指定して、新しいトークンを作成します

3. AI アシスタントを設定する

MCP 設定ファイルに以下を追加します。

stdio モードの場合（最も一般的）：

{
  "mcpServers": {
    "forgejo": {
      "command": "forgejo-mcp",
      "args": [
        "--transport", "stdio",
        "--url", "https://your-forgejo-instance.org"
      ],
      "env": {
        "FORGEJO_ACCESS_TOKEN": "<your personal access token>",
        "FORGEJO_USER_AGENT": "forgejo-mcp/1.0.0"
      }
    }
  }
}

streamable HTTP モードの場合（リモート／Claude.ai での利用に推奨）：

{
  "mcpServers": {
    "forgejo": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

streamable HTTP モードを使用する場合は、先にサーバーを起動します。

forgejo-mcp --transport http --url https://your-forgejo-instance.org --token <your-token>

マルチテナント HTTP モード（任意）：

単一の集中管理された forgejo-mcp インスタンスを実行し、各クライアントが標準の HTTP Authorization ヘッダーを使って独自のトークンを渡すことができます。これにより、1 つのサーバーから複数のユーザーまたはエージェントにサービスを提供できます。

1. サーバーを起動します（グローバルトークンなしでも起動できます）。

   forgejo-mcp --transport http --url https://your-forgejo-instance.org
   

2. クライアントは各リクエストに固有のトークンを含めます。
   • Authorization: token <token>（Forgejo 形式）
   • Authorization: Bearer <token>（OAuth2／MCP 形式）
   • 注：スキーム（token または Bearer）の大文字と小文字は区別されません。

コピーしてそのまま使える手順については、demos/multi-tenant-http.md を参照してください。

サーバーをネットワークに公開する

デフォルトでは、sse および http トランスポートはループバックのみで待ち受けるため、このマシンの外部から接続できません。これは、ローカルで実行するサーバーに関する Model Context Protocol のガイダンスに沿ったものであり、動作の変更点です。以前のバージョンでは、すべてのネットワークインターフェイスで待ち受けていました。デフォルトの localhost は両方のループバックファミリーにバインドされるため、localhost を 127.0.0.1 または ::1 のどちらかに解決するクライアントも接続できます。どちらかのファミリーでポートがすでに使用されている場合、サーバーは起動を拒否します。一方のファミリーでサービスを提供し、もう一方のファミリーではクライアントがそのポートを使用している別のプログラムに接続してしまう事態を避けるためです。マシンでまったく使用できないファミリー（たとえば IPv6 が無効の場合）はスキップされ、その旨が起動ログに記録されます。

名前ではなくアドレスを指定し、--host 127.0.0.1 または --host ::1 のようにすると、そのファミリーだけにバインドされます。もう一方のファミリーが、このサーバーから「存在しない」と判別できない形でマシン上で使用できず、そのため起動が拒否される場合に使用してください。

コンテナー内でサーバーを実行する場合や、リモートクライアントにサービスを提供する場合は、明示的な指定が必要です。 デフォルトでは、マシンの外部から（コンテナー内の場合はコンテナーの外部から）接続できません。

• --host にネットワークから到達可能なアドレスを指定します（コンテナー内では、すべてのインターフェイスを対象とする 0.0.0.0 が一般的な選択肢です）。
• クライアントが使用するホスト名を --allowed-hosts に指定します。これは任意ではなく必須です。指定しないままネットワークから到達可能なアドレスで起動しようとすると、サーバーは起動を拒否します。起動後にすべてのリクエストを拒否するのではなく、起動時に拒否されます。

Host ヘッダーが指定したホスト名のいずれにも一致しないリクエストは、403 Forbidden で拒否されます。ループバックリスナーではループバック名が常に許可されるため、プロキシのホスト名を指定しても、同じマシンから直接接続できなくなることはありません。

ブラウザークライアント。 Origin ヘッダーを含むリクエストは、そのオリジンが --allowed-origins に登録されていない限り拒否されます。デフォルトでは、このオプションは空です。オリジンはスキーム、ホスト、ポートを含む全体で比較されます。Origin のポートはこのサーバーではなく、リクエストを行うページに属するためです。Origin ヘッダーをまったく含まないリクエストには影響しません。MCP クライアントはブラウザーではないため、通常はこのケースに該当します。

sse と http での認証

これらのトランスポートでは、各リクエストにそれぞれ独自の Authorization ヘッダーを含める必要があります。ヘッダーのないリクエストは 401 Unauthorized で拒否され、サーバーに設定されたトークンを使って処理されることはありません。これは、前述のマルチテナント構成で想定されている動作であり、この構成を安全に公開できる理由でもあります。

stdio では、これまでどおり、ヘッダーがない場合は設定済みのトークンが代わりに使われます。stdio の動作に変更はありません。

sse または http でシングルユーザー向けにデプロイし、以前の動作に戻したい場合は、--allow-operator-token-fallback で復元できます。使う前に、その意味を理解してください。ポートに接続できるクライアントは、認証情報を提示せずに、トークンに紐づくユーザーとして動作できます。この設定が有効な間は、起動ログにその旨が大きく表示されます。

SSE モード（従来の HTTP ベース）の場合：

{
  "mcpServers": {
    "forgejo": {
      "url": "http://localhost:8080/sse"
    }
  }
}

SSE モードを使用する場合は、先にサーバーを起動します。

forgejo-mcp --transport sse --url https://your-forgejo-instance.org --token <your-token>

通知ストリームとハートビート

sse と http では、サーバーが自身のメッセージ（通知、進行状況、サーバーリクエスト）を配信するためにストリームを開いたままにします。セッションがアイドル状態の間、このストリームには何も流れません。無通信の状態が長く続くと、クライアント、プロキシ、NAT デバイスはストリームを切断します。ある MCP クライアントは 6 分後に接続を中断します。そのため、サーバーは --heartbeat の間隔（デフォルトは 30s）ごとに、ストリームへ JSON-RPC の ping を書き込みます。以前のように無通信に戻すには、--heartbeat 0 を設定します。

OAuth リソースサーバーとしてのリモート運用

--auth-mode resource-server を指定すると、MCP 認可仕様の定義に従い、http トランスポートが OAuth 2.0 リソースサーバーになります。クライアントは Forgejo トークンを送信しなくなります。選択した OpenID Connect プロバイダーにログインし、そのプロバイダーの JWT アクセストークンを送信します。サーバーはそのトークンを検証し、呼び出し元向けの有効期間が 5 分の JWT に署名して、Forgejo 16 の Authorized Integration を通じて Forgejo に提示します。Forgejo トークンを設定する必要はなく、呼び出し元のアクセストークンが Forgejo に届くこともありません。

このモードには、次のものが必要です。

• Forgejo 16.0 以降。
• JWT アクセストークンを発行し、ユーザーごとのクレーム（デフォルトは forgejo_aud）を追加できる OpenID Connect プロバイダー。そのクレームには、そのユーザーの Authorized Integration のオーディエンスが格納されます。
• サーバーの公開 HTTPS オリジン。Forgejo がそこからサーバーの issuer ドキュメントを取得するためです。
• 署名鍵ファイル：EC P-256 または P-384、Ed25519、または 2048 ビット以上の RSA。

forgejo-mcp --transport http --url https://forgejo.example.org \
  --host 0.0.0.0 --allowed-hosts mcp.example.org \
  --auth-mode resource-server \
  --authorization-server https://id.example.org \
  --resource https://mcp.example.org/mcp \
  --forgejo-jwt-issuer https://mcp.example.org/issuer \
  --forgejo-jwt-signing-key-file /run/credentials/forgejo-mcp.service/signing-key

このモードはオプトインです。--auth-mode を指定しなければ、上記のすべての動作は変わりません。このモードでは、サーバーは /mcp、保護されたリソースのメタデータ、および issuer パス配下のディスカバリードキュメントとキーセットにのみ応答します。安全に提供できない構成では起動を拒否し、修正が必要な設定を示します。署名鍵は、issuer を信頼するすべてのユーザーのために使われるため、置き換え対象となる Forgejo トークンと同様に厳重に管理してください。

• 運用者ガイド：ID プロバイダーの要件、デプロイの順序、プロキシのルール、鍵のローテーション、Zitadel を使った詳細な例。
• ユーザーガイド：Authorized Integration の作成、必須の sub クレームルール、MCP クライアントの設定。

4. 使い始める

MCP 対応の AI アシスタントを開いて、次を試してください。

List all my repositories

利用可能なツール

ツール	説明
ユーザー
get_my_user_info	認証済みユーザーの情報を取得します
check_notifications	ユーザー通知を確認して一覧表示します
get_notification_thread	1件の通知スレッドの詳細情報を取得します
mark_notification_read	1件の通知スレッドを既読にします
mark_all_notifications_read	すべての通知を確認済みにします
list_repo_notifications	1つのリポジトリに絞り込んで通知を一覧表示します
mark_repo_notifications_read	特定のリポジトリのすべての通知を既読にします
search_users	ユーザーを検索します
リポジトリ
list_my_repos	自分が所有するすべてのリポジトリを一覧表示します
get_repo	所有者と名前を指定してリポジトリを1つ取得します
create_repo	新しいリポジトリを作成します
fork_repo	リポジトリをフォークします
edit_repo	リポジトリの設定を編集します。渡したフィールドのみが変更され、省略したフィールドは変更されません。フィールドを指定しない場合はエラーになります。
search_repos	リポジトリを検索します
トピック
list_repo_topics	リポジトリのトピックを一覧表示します。page（デフォルトは1）＋limit（デフォルトは100）の範囲で取得し、{topics, page, limit, count}を返します。
set_repo_topics	すべてのトピックを置き換えます。topicsには必須のカンマ区切り文字列を指定します。空文字列を指定するとクリアされます。無効な名前はリクエスト前に拒否されます。
add_repo_topic	トピックを1つ追加します
delete_repo_topic	トピックを1つ削除します
ブランチ
list_branches	リポジトリ内のすべてのブランチを一覧表示します
create_branch	新しいブランチを作成します
delete_branch	ブランチを削除します
ブランチ保護
list_branch_protections	リポジトリのブランチ保護ルールを一覧表示します。page（1始まり）＋limit（ページサイズ）の範囲で取得します。レスポンスにはpage／limitが含まれるため、呼び出し側は次のページを取得できます。
get_branch_protection	rule名でルールを1つ取得します
create_branch_protection	ルールを作成します。branch_nameが必要です。status_check_contextsには、必須チェックのカンマ区切りリスト（例："ci/build,ci/test"）を指定します。
edit_branch_protection	rule名でルールを編集します。渡したフィールドのみが変更され、省略したフィールドは変更されません。
delete_branch_protection	rule名でルールを削除します
Webhook
list_repo_hooks	リポジトリのWebhookを一覧表示します。page（デフォルトは1）＋limit（デフォルトは30、サーバーによる上限なし）の範囲で取得し、ForgejoがX-Total-Countを返す場合はtotal_countも返します。
get_repo_hook	IDでリポジトリのWebhookを1つ取得します
create_repo_hook	リポジトリのWebhookを作成します。シークレットは受け付けますが、レスポンスには決して含まれません。
edit_repo_hook	リポジトリのWebhookを編集します。渡したフィールドのみが変更され、省略したフィールドは変更されません。
delete_repo_hook	IDでリポジトリのWebhookを削除します
test_repo_hook	リポジトリのWebhookにテスト配信を実行します — 警告：実際のHTTP配信が発生します
ファイル
get_file_content	ファイルの内容を取得します。任意のstart_line／end_lineで、1始まりの両端を含む行範囲を指定できます（ファイルの範囲内に収まるよう調整され、with_metadata=trueの場合は無視されます）。
list_repo_contents	パスにあるファイルとディレクトリを一覧表示します。path=""を指定するとリポジトリのルートを一覧表示します。1階層分を返します。ツリー全体を取得するには、recursive=trueでget_repo_treeを使用します。
get_repo_tree	Gitツリーを取得します。recursive=trueを指定すると、1回のレスポンスでファイルツリー全体を返します（サーバーのツリーエンドポイントのサイズ上限に従います）。recursive=false（デフォルト）では1階層分を返します。
create_file	新しいファイルを作成します。プレーンテキストのcontentまたはバイナリーセーフなcontent_base64（標準Base64形式のみ）のどちらか一方を指定します。
update_file	既存のファイルを更新します。プレーンテキストのcontentまたはバイナリーセーフなcontent_base64（標準Base64形式のみ）のどちらか一方を指定します。
delete_file	ファイルを削除します
change_files	ネイティブのForgejoコミット1件で複数のファイルをアトミックに作成、更新、削除します。作成／更新操作ではcontentまたはcontent_base64を指定できます。
コミット
list_repo_commits	リポジトリ内のコミットを一覧表示します
get_commit_statuses	40文字の完全なSHAを指定して、コンテキストごとのコミットステータスを一覧表示します。page（デフォルトは1）＋limit（デフォルトは30、最大50）の範囲で取得し、{sha, statuses, page, limit, count, total_count}を返します。total_countはForgejoがX-Total-Countを返す場合のみ含まれます。集計ステータスはコミットステータスリソースに含まれます。Actionsの実行ではありません（list_workflow_runs）。
課題
list_repo_issues	リポジトリの課題を一覧表示します（page／limit）。任意のsortでサーバー側の並べ替えを指定できます：relevance、latest、oldest、recentupdate、leastupdate、mostcomment、leastcomment、nearduedate、farduedate（最後の2つは期限による並べ替え方向です）。
search_issues	1人の所有者が持つすべてのリポジトリを対象に課題を検索します（page／limit）。{issues,page,limit,count,has_next,total_count}を返します。total_countはForgejoがX-Total-Countを返す場合のみ含まれます
get_issue_by_index	指定した課題を取得します
create_issue	新しい課題を作成します。任意のlabels（カンマ区切りの名前またはID）、assignees（カンマ区切りのユーザー名）、milestone（数値ID）は、課題の作成と同じリクエストで適用されます。
add_issue_labels	課題にラベルを追加します。labelsにはカンマ区切りのラベル名または数値IDを指定します。認識されない名前があるとエラーになり、何も適用されません。
remove_issue_labels	課題からラベルを削除します。labelsにはカンマ区切りのラベル名または数値IDを指定します。
update_issue	既存の課題を更新します（数値のマイルストーンIDが必要です）。due_dateで期限を設定します（RFC3339）。clear_due_date=trueで期限を削除します。両方は同時に指定できません。両方を設定するとエラーになり、どちらも省略すると期限は変更されません。set_labelsで課題のラベル一式を置き換えます（名前またはID）。空文字列を指定するとすべてのラベルがクリアされます。
issue_state_change	課題をオープンまたはクローズします
list_issue_dependencies	指定した課題が依存する課題を一覧表示します。page（1始まり）＋limit（ページサイズ）の範囲で取得します。レスポンスにはpage／limitが含まれるため、呼び出し側は次のページを取得できます。
list_issue_dependents	指定した課題に依存する課題を一覧表示します。page（1始まり）＋limit（ページサイズ）の範囲で取得します。レスポンスにはpage／limitが含まれるため、呼び出し側は次のページを取得できます。
add_issue_dependency	ある課題が別の課題に依存するように設定します。依存先は別のリポジトリにある場合があります。任意のdepends_on_owner／depends_on_repoを省略すると、owner／repoがデフォルトになります。
remove_issue_dependency	課題から依存関係を削除します。別のリポジトリにある依存関係の場合、任意のdependency_owner／dependency_repoを省略すると、owner／repoがデフォルトになります。
list_repo_milestones	ID付きでマイルストーンを一覧表示します（update_issueと併用）
list_repo_labels	ID付きでラベルを一覧表示します。組織所有のリポジトリでは組織レベルのラベルも統合されます（含めない場合はinclude_org_labels=falseを設定）。各項目にはscopeフィールド（"repo"または"org"）と、exclusiveおよびis_archived（falseも省略されずに含まれます）が含まれます。
list_org_labels	ID付きで組織レベルのラベルを一覧表示します。割り当てツールではラベル名を直接指定できるため、このツールはラベルの確認と、リポジトリと組織の両方のスコープに同じ名前が存在するまれなケースに使用します。各項目にはexclusiveとis_archivedが含まれます。
create_repo_label	リポジトリラベルを作成します（name、6桁の16進数形式のcolor、任意のdescription、exclusive、is_archived）。exclusive=trueにはスコープ付きの名前（どちらの端でもない位置に/を含む名前）が必要です。数値のidを返します。add_issue_labelsでは名前も指定できます。
edit_repo_label	リポジトリラベルを編集します（PATCH — 渡したフィールド（name、color、description、exclusive、is_archived）のみが変更されます）。exclusiveのみの編集では現在の名前を再取得しません。
delete_repo_label	リポジトリラベルを削除します。デフォルトでは、ラベルが使用中の場合は削除を拒否し、使用数を報告します。上書きするにはdelete_mode=forceを設定します。
get_repo_label	数値のidでリポジトリラベルを1つ取得します。exclusiveとis_archivedを含みます。
create_org_label	組織レベルのラベルを作成します。フィールドはcreate_repo_labelと同じです。
edit_org_label	組織レベルのラベルを編集します（PATCHの動作。exclusiveとis_archivedを含みます）。
delete_org_label	組織レベルのラベルを削除します。使用中かどうかの確認では、表示可能な組織リポジトリ全体の使用数を数えます（ベストエフォート）。delete_mode=forceで上書きできます。
get_org_label	数値のidで組織レベルのラベルを1つ取得します。exclusiveとis_archivedを含みます。
コメント
list_issue_comments	課題またはPRのコメントを一覧表示します
get_issue_comment	指定したコメントを取得します
create_issue_comment	課題またはPRにコメントを追加します
edit_issue_comment	コメントを編集します
delete_issue_comment	コメントを削除します
プルリクエスト
list_repo_pull_requests	リポジトリのプルリクエストを一覧表示します
get_pull_request_by_index	指定したプルリクエストを取得します
create_pull_request	新しいプルリクエストを作成します
update_pull_request	既存のプルリクエストを更新します
list_pull_reviews	プルリクエストのレビューを一覧表示します
get_pull_review	指定したプルリクエストのレビューを取得します
list_pull_review_comments	プルリクエストのレビューに付いたコメントを一覧表示します
list_pull_request_files	プルリクエストで変更されたファイルを一覧表示します（ページネーション対応）。返されたファイル名をget_pull_request_diffのfile_path引数に指定してください。
get_pull_request_diff	プルリクエストの統合差分を取得します。任意のfile_pathを指定すると、そのファイルの差分部分のみを返します（変更前または変更後のパスのどちらにも一致します）。
merge_pull_request	プルリクエストをマージします（方式：merge／rebase／rebase-merge／squash。任意のtitle／message／delete-branch／force-merge／wait-for-checksを指定できます）。
create_pull_review	プルリクエストのレビューを作成します（状態：APPROVED／REQUEST_CHANGES／COMMENT）。任意でインラインコメントを指定できます。
submit_pull_review	保留中のプルリクエストレビューを送信します
dismiss_pull_review	プルリクエストのレビューを却下します
delete_pull_review	保留中のプルリクエストレビューを削除します
create_review_requests	特定のユーザーまたはチームにレビューを依頼します
delete_review_requests	保留中のレビュー依頼を取り消します
パッケージ
list_packages	ユーザーまたは組織のパッケージバージョンを一覧表示します（バージョンごとに1行）。任意でtypeとqを指定できます。サーバー側でpage／limitによるページネーションを行います（デフォルトは30、最大50）。エンベロープは{packages, page, limit, count, has_next, total_count?}です。所有者が存在しない場合は空のリストではなくエラーになります
get_package	パッケージバージョンを1つ取得します。所有者／作成者のユーザー情報は埋め込まれません
delete_package	パッケージバージョンを1つ削除します（同名のすべてのバージョンではありません）。事前確認は行いません。4xx／5xxはエラーのまま返されます
list_package_files	パッケージバージョン1つのファイルを一覧表示します。クライアント側でpage／limitによるページネーションを行います（デフォルトは30、最大50）。エンベロープは{files, page, limit, count, has_next, total_count}です（total_countは取得したリストの長さです）
Actions
dispatch_workflow	workflow_dispatchイベントでワークフロー実行をトリガーします
list_workflow_runs	ステータス、イベント、実行番号、またはSHAによる任意の絞り込みを行ってワークフロー実行を一覧表示します
get_workflow_run	データベースIDで特定のワークフロー実行の詳細を取得します
list_action_run_jobs	クライアント側のpageおよびlimitの範囲指定で、Forgejo v16以降のワークフロー実行のジョブを一覧表示します
get_action_job_logs	再開可能なoffsetとmax_bytesの範囲指定で、Forgejo v16以降のジョブログを読み取ります。デフォルトでは末尾を返します
cancel_workflow_run	保留中または実行中のワークフロー実行をキャンセルします。すでに終了した実行も成功を返します（HTTP 204）。実行の状態は変更されません
delete_workflow_run	完了したワークフロー実行を削除します。実行中の場合はAPIエラーになります。実行とそのジョブログを削除し、Forgejoはその実行のアーティファクトを削除済みとして扱います
list_action_run_artifacts	ワークフロー実行のアーティファクトを一覧表示します。サーバー側でpage／limitによるページネーションを行います（デフォルトは30、最大50）。任意でnameによる絞り込みができます。エンベロープは{artifacts, page, limit, count, total_count?}です
get_action_artifact	Actionsアーティファクト1件のメタデータを取得します。zipはダウンロードしません
list_repo_action_secrets	リポジトリのActionsシークレットを一覧表示します（名前のみ。Forgejoは値を返しません）。クライアント側でpage／limitによるページネーションを行います（デフォルトは30、最大50）
create_or_update_repo_action_secret	リポジトリのActionsシークレットを作成または更新します。同じ名前の既存のシークレットは上書きされ、値が返されることはありません
delete_repo_action_secret	リポジトリのActionsシークレットを削除します
list_org_action_secrets	組織のActionsシークレットを一覧表示します（名前のみ。Forgejoは値を返しません）。クライアント側でpage／limitによるページネーションを行います（デフォルトは30、最大50）
create_or_update_org_action_secret	組織のActionsシークレットを作成または更新します。同じ名前の既存のシークレットは上書きされ、値が返されることはありません
delete_org_action_secret	組織のActionsシークレットを削除します
組織
list_my_orgs	自分の組織を一覧表示します
list_user_orgs	ユーザーの組織を一覧表示します
get_org	組織の詳細を取得します
create_org	組織を作成します
edit_org	組織の設定を編集します
delete_org	組織を削除します — 破壊的で取り消せない操作：すべてのリポジトリ、チーム、データが完全に削除されます
list_org_members	組織のメンバーを一覧表示します
check_org_membership	ユーザーが組織のメンバーかどうかを確認します
remove_org_member	組織からメンバーを削除します
list_org_teams	組織のチームを一覧表示します
search_org_teams	組織のチームを検索します
create_org_team	組織にチームを作成します
add_team_member	チームにユーザーを追加します
remove_team_member	チームからユーザーを削除します
add_team_repo	チームにリポジトリを追加します
remove_team_repo	チームからリポジトリを削除します
時間トラッキング
list_issue_tracked_times	課題またはPRの記録済み時間を一覧表示します
list_repo_tracked_times	リポジトリ全体の記録済み時間を一覧表示します
list_my_tracked_times	自分の記録済み時間を一覧表示します
add_issue_time	課題またはPRに時間を記録します（秒数または15mのような期間を指定できます）
reset_issue_time	課題またはPRの記録済み時間をすべて削除します（破壊的操作）
delete_issue_time_entry	IDで記録済み時間を1件削除します
start_issue_stopwatch	課題またはPRのストップウォッチを開始します
stop_issue_stopwatch	実行中のストップウォッチを停止し、経過時間を記録します
cancel_issue_stopwatch	実行中のストップウォッチを記録せずにキャンセルします
list_my_stopwatches	現在実行中のストップウォッチを一覧表示します
添付ファイル
list_issue_attachments	課題またはPRの添付ファイルを一覧表示します
get_issue_attachment	課題／PRの添付ファイル1件のメタデータを取得します
download_issue_attachment	課題／PRの添付ファイルをダウンロードします（1 MiB未満の場合はインラインで返し、それ以外はメタデータとURLを返します）
create_issue_attachment	課題またはPRに新しい添付ファイルをアップロードします（Base64コンテンツまたはMCPホスト上のファイルパスを指定できます）
edit_issue_attachment	課題／PRの添付ファイルの名前を変更します
delete_issue_attachment	課題／PRの添付ファイルを削除します
list_comment_attachments	課題／PRのコメントに付いた添付ファイルを一覧表示します
get_comment_attachment	コメントの添付ファイル1件のメタデータを取得します
download_comment_attachment	コメントの添付ファイルをダウンロードします（1 MiB未満の場合はインラインで返し、それ以外はメタデータとURLを返します）
create_comment_attachment	課題／PRのコメントに新しい添付ファイルをアップロードします（Base64コンテンツまたはMCPホスト上のファイルパスを指定できます）
edit_comment_attachment	コメントの添付ファイルの名前を変更します
delete_comment_attachment	コメントの添付ファイルを削除します
リリース
list_releases	リポジトリのリリースを一覧表示します（page／limitに対応し、クライアント側でstate（all／draft／prerelease／published）による絞り込みができます）
get_release_by_id	数値IDでリリースを取得します
get_release_by_tag	タグ名でリリースを取得します
get_latest_release	最新のドラフトではないリリース、かつプレリリースではないリリースを取得します
create_release	新しいリリースを作成します（タグも作成するにはtarget_commitishを指定します）
edit_release	既存のリリースのフィールドを更新します（指定したフィールドのみ送信されます）
delete_release	数値IDでリリースを削除します — 破壊的操作
delete_release_by_tag	タグ名でリリースを削除します — 破壊的操作です。タグを確認してください
list_release_attachments	リリースの添付ファイルを一覧表示します（レスポンス全体を取得し、クライアント側で切り出します）
get_release_attachment	リリースの添付ファイル1件のメタデータを取得します
download_release_attachment	リリースの添付ファイルをダウンロードします（1 MiB未満の場合はインラインで返し、それ以外はメタデータとURLを返します）
create_release_attachment	リリースに新しい添付ファイルをアップロードします（Base64コンテンツまたはMCPホスト上のファイルパスを指定できます）
edit_release_attachment	リリースの添付ファイルの名前を変更します
delete_release_attachment	リリースの添付ファイルを削除します — 破壊的操作
Wiki
list_wiki_pages	page／limitを使ってページを一覧表示します。has_nextを返し、ForgejoがX-Total-Countを返す場合はtotal_countも返します。total_countは上流のWikiツリーの生のエントリー数を数えるため、サブディレクトリを含むWikiでは一覧表示されたページ数を超える場合があります。正確な総数ではなく上限値です。
get_wiki_page	デコード済みのMarkdownを読み取ります。任意のstart_line／end_lineを指定でき、常にtotal_linesを返します。
get_wiki_revisions	page／limitを使ってリビジョン履歴を一覧表示します。has_nextとtotal_countを返します。total_countはレスポンス本文に報告される、そのページのリビジョン総数です。
create_wiki_page	ページを作成し、サーバーで正規化されたpage_nameを返します。スラッシュ区切りのタイトルは階層構造のないフラットなサブページの命名規則であり、親ページは自動作成されません。既存のタイトルは上書きされます。
update_wiki_page	正規化されたpage_nameで内容／タイトルを更新します。最後に書き込んだ内容が優先されます。
delete_wiki_page	正規化されたpage_nameでページを削除します。
サーバー
get_forgejo_mcp_server_version	MCP サーバーのバージョンを取得します

リソース

MCP リソーステンプレートは、forgejo:// スキームを使用して、Forgejo のエンティティを URI で指定可能なリソースとして公開します。URI スキームはインスタンス間でポータブルなため、同じ形式の URI をあらゆる Forgejo インスタンスで使用でき、Forgejo のウェブリンクとも競合しません。resources/templates/list と resources/read に対応するクライアント（Claude Code、Claude Desktop、Codex、Cursor）は、これらの URI を直接解決できます。リソーステンプレートに対応していないクライアントも、引き続き上記のツールを使用できます。機能が削除されることはありません。

リソースが MCP ツールに置き換わることはありません。既存のすべての list/get ツールは引き続き利用できます。リソースは、LLM コンテキストからの自動解決や、コミットなどの不変エンティティのコンテンツアドレス可能なキャッシュを目的として追加された、URI で指定可能な読み取り手段です。

リストを埋め込むリソース（issue、pr）では、埋め込み配列の項目数を 30 件に制限します。切り詰められた場合、JSON ペイロードには、全件リストを取得するために呼び出すべき対応する list_* ツールを示すセンチネルが含まれます。

リソースとツールの使い分け： sha またはインデックスが手元にある場合はリソースを優先し、一覧表示や検索を行う場合はツールを優先してください。

URI テンプレート	エンティティ	備考
forgejo://owner/{owner}	application/json	ログイン名で指定するユーザーまたは組織のプロフィールです。まずユーザーを検索し、見つからない場合は組織を検索します。
forgejo://repo/{owner}/{repo}	application/json	リポジトリの概要です。識別情報と件数を含み、リストは埋め込まれません。
forgejo://repo/{owner}/{repo}/commit/{sha}	コミットメタデータ	sha ごとに不変です。JSON と Markdown のサイドカーを返します。sha は 40 桁の 16 進数である必要があります。
forgejo://repo/{owner}/{repo}/commit/{sha}/status	application/json	sha の CI ステータスを集約したものです。集約状態と、上限付きのコンテキストごとのステータスを含みます（上限 30 件。続きがある場合の番兵名は get_commit_statuses ツール）。
forgejo://repo/{owner}/{repo}/issue/{index}	application/json（+ text/markdown サイドカー）	Issue のメタデータ、レンダリング済みの本文、上限付きの最近のコメントを含みます（上限 30 件。続きがある場合の番兵名は list_issue_comments）。
forgejo://repo/{owner}/{repo}/issues{?state,labels,page,limit}	application/json	Issue の上限付きリストを行形式で返します。インデックス、タイトル、状態、作成者、ラベル、担当者、マイルストーン、コメント数、タイムスタンプ、期限を含み、本文は含みません。state は {open, closed, all} のいずれか（既定値は open）です。labels はカンマ区切りです。上限は 30 件で、続きがある場合の番兵名は list_repo_issues です。本文を取得するには、単一 Issue のリソースを参照してください。
forgejo://repo/{owner}/{repo}/{kind}/{index}/comment/{id}	application/json（+ text/markdown サイドカー）	id で指定する単一コメントです。kind は {issue, pr} のいずれかです。
forgejo://repo/{owner}/{repo}/{kind}/{index}/comments{?page,limit}	application/json	本文全体を含む、上限付きのコメントスレッドです（単一 Issue のリソースでは本文を 200 文字で抜粋します）。kind は {issue, pr} のいずれかです。上限は 30 件で、続きがある場合の番兵名は list_issue_comments です。
forgejo://repo/{owner}/{repo}/pr/{index}	application/json（+ text/markdown サイドカー）	PR のメタデータ、head/base ref、マージ可能性、上限付きの最近のコメント（上限 30 件。続きがある場合の番兵名は list_issue_comments）とレビュー（上限 30 件。続きがある場合の番兵名は list_pull_reviews）を含みます。
forgejo://repo/{owner}/{repo}/branch_protections	application/json	ブランチ保護ルールの上限付きリストです。
forgejo://repo/{owner}/{repo}/branch_protection/{rule}	application/json	単一のブランチ保護ルールです。ルール名はブランチパターンなので、リテラルの / は %2F、スペースは %20 にエンコードしてください（release%2Fv1）。生の / では解決されません。
forgejo://repo/{owner}/{repo}/hooks	application/json	リポジトリの Webhook の上限付きリストです（上限 30 件。続きがある場合の番兵名は list_repo_hooks）。シークレットは返されません。
forgejo://repo/{owner}/{repo}/hook/{id}	application/json	id で指定する単一のリポジトリ Webhook です。シークレットは返されません。
forgejo://repo/{owner}/{repo}/label/{id}	application/json	数値 id で指定する単一のリポジトリラベルです。
forgejo://repo/{owner}/{repo}/labels{?page,limit}	application/json	リポジトリラベルの上限付きリストです（上限 30 件。続きがある場合の番兵名は list_repo_labels）。
forgejo://org/{org}/labels{?page,limit}	application/json	組織レベルのラベルの上限付きリストです（上限 30 件。続きがある場合の番兵名は list_org_labels）。
forgejo://repo/{owner}/{repo}/wiki/{pageName}	application/json（+ text/markdown サイドカー）	上限付きのリビジョンと、1 MiB を上限とする Markdown を含む Wiki ページです。返された正規化済みの page_name を使用してください。URI ではリテラルの / を %2F、スペースを %20 にエンコードしてください（すでに正規化済みの名前を二重にエンコードしないでください）。

Guides/Setup のようにスラッシュで区切ったタイトルは、サブページの命名規則として便利です。 ただし、Forgejo はページをフラットなリストに保存します。Guides を自動作成することも、 親子関係を記録することもありません。読者に親ページが必要な場合は別途作成し、 以降の呼び出しでは、作成または一覧取得で返された正規化済みの page_name を必ず使用してください。 ここに記載した Wiki REST の動作は Forgejo 15.0.4+gitea-1.22.0 に対して実機テスト済みです。MCP デモ全体は 16.0.0+gitea-1.22.0 に対して再生し、正常に完了しました。これはテスト済みの範囲であり、 その間のすべてのバージョンや、異なるプロキシ構成のデプロイ環境での動作を保証するものではありません。

クライアントの互換性

クライアント	resources/templates/list	resources/read
Claude Code	対応	対応
Claude Desktop	対応	対応
Codex	対応	対応
Cursor（現行）	対応	対応
旧式／最小限のクライアント	ツールのみ	ツールのみ

デモ

上記のツールをエンドツーエンドで解説する、コピー＆ペースト可能な手順は、トピック（ラベル、添付ファイル、時間追跡、通知、組織、I/O 範囲を限定したコードレビュー、トランスポート）ごとにまとめられ、demos/ にあります。各デモでは、codeberg.org に対して実行した ./forgejo-mcp --cli の実際の呼び出しと、その出力を組み合わせています。

CLI モード

MCP サーバーを実行せずに、コマンドラインから任意のツールを直接呼び出せます。シェルスクリプト、CI/CD パイプライン、Claude Code のスキルで役立ちます。

# List all available tools (grouped by domain)
forgejo-mcp --cli list

# Invoke a tool with JSON arguments
forgejo-mcp --cli get_issue_by_index --args '{"owner":"goern","repo":"forgejo-mcp","index":1}'

# Pipe JSON arguments via stdin
echo '{"owner":"goern","repo":"forgejo-mcp"}' | forgejo-mcp --cli list_repo_issues

# List recent workflow runs (text output)
forgejo-mcp --cli list_workflow_runs \
  --args '{"owner":"goern","repo":"forgejo-mcp"}' \
  --output=text

# List only failed runs
forgejo-mcp --cli list_workflow_runs \
  --args '{"owner":"goern","repo":"forgejo-mcp","status":"failure"}' \
  --output=text

# Run-scoped tools (list_action_run_jobs, cancel_workflow_run, ...) take the
# database run ID printed by list_workflow_runs (e.g. #2671), not the per-repo run
# number in the web URL (.../actions/runs/222). To map a web-URL number to a
# run ID, add "run_number":222 to the list_workflow_runs args.

# List jobs and inspect the tail of a failed job (Forgejo v16+)
forgejo-mcp --cli list_action_run_jobs \
  --args '{"owner":"goern","repo":"forgejo-mcp","run_id":123}' \
  --output=text
forgejo-mcp --cli get_action_job_logs \
  --args '{"owner":"goern","repo":"forgejo-mcp","job_id":456,"max_bytes":32768}' \
  --output=text

# Forgejo's run-wide ZIP log endpoint has no Range support. Enumerate jobs and
# fetch their bounded plaintext logs instead.

# List artifacts of a run, then read one artifact's metadata (no zip download)
forgejo-mcp --cli list_action_run_artifacts \
  --args '{"owner":"goern","repo":"forgejo-mcp","run_id":123,"limit":30}' \
  --output=text
forgejo-mcp --cli get_action_artifact \
  --args '{"owner":"goern","repo":"forgejo-mcp","artifact_id":789}' \
  --output=text

# List package versions for an owner, then inspect one version's files
forgejo-mcp --cli list_packages \
  --args '{"owner":"OWNER","type":"container","limit":30}' \
  --output=text
forgejo-mcp --cli get_package \
  --args '{"owner":"OWNER","type":"container","name":"app","version":"1.0.0"}' \
  --output=text
forgejo-mcp --cli list_package_files \
  --args '{"owner":"OWNER","type":"container","name":"app","version":"1.0.0"}' \
  --output=text

# delete_package removes one version. Do not invoke it against a registry you do not own.

# cancel_workflow_run is 204 even when the run already finished.
# delete_workflow_run only succeeds for a completed run; a live run is an error.

# Show a tool's parameters
forgejo-mcp --cli create_issue --help

# Control output format (json or text)
forgejo-mcp --cli list --output=json
forgejo-mcp --cli get_my_user_info --args '{}' --output=text

CLI モードでは、MCP サーバーモードと同じ FORGEJO_URL および FORGEJO_ACCESS_TOKEN の設定が必要です。ツールの結果は既定で JSON として stdout に書き込まれ、エラーは stderr に書き込まれ、終了コードは 0 以外になります。

設定オプション

コマンドライン引数または環境変数を使用してサーバーを設定できます。

CLI 引数	環境変数	説明
--url	FORGEJO_URL	Forgejo インスタンスの URL
--token	FORGEJO_ACCESS_TOKEN	個人用アクセストークン
--debug	FORGEJO_DEBUG	デバッグモードを有効にします
--transport	-	トランスポートモード：stdio、sse、または http
--sse-port	-	SSE モードのポート（デフォルト：8080）
--http-port	-	ストリーミング可能な HTTP モードのポート（デフォルト：8080）
--host	FORGEJO_MCP_HOST	sse と http のトランスポートがバインドするアドレス（デフォルト：localhost。このマシンからのみ到達可能で、127.0.0.1 と ::1 の両方にバインドします。どちらかのアドレスを指定すると、そのアドレスのアドレスファミリーのみにバインドします）
--allowed-hosts	FORGEJO_MCP_ALLOWED_HOSTS	このサーバーが応答する Host 名をカンマ区切りで指定します。--host がループバック以外の場合は必須です
--allowed-origins	FORGEJO_MCP_ALLOWED_ORIGINS	Origin ヘッダーの送信を許可する Web オリジンを完全なオリジン（https://console.example.org）でカンマ区切りで指定します。デフォルトは空です
--allow-operator-token-fallback	FORGEJO_MCP_ALLOW_OPERATOR_TOKEN_FALLBACK	sse／http で、Authorization ヘッダーのないリクエストをこのサーバー自身のトークンで処理します。デフォルトでは無効です
--heartbeat	FORGEJO_MCP_HEARTBEAT	sse／http が通知ストリームに JSON-RPC の ping を書き込む間隔です。アイドルタイムアウトが設定されたクライアントやプロキシが接続を維持できるようにします（デフォルト：30s。0 の場合は送信しません）
--auth-mode	FORGEJO_MCP_AUTH_MODE	passthrough（デフォルト）または resource-server。OAuth リソースサーバーとしてのリモート操作を参照してください
--authorization-server	FORGEJO_MCP_AUTHORIZATION_SERVER	resource-server モード：OpenID Connect プロバイダーの発行者 URL。バイト単位で比較されます
--resource	FORGEJO_MCP_RESOURCE	resource-server モード：MCP エンドポイントの正規 URI。例：https://mcp.example.org/mcp。パスは /mcp である必要があります
--resource-audience	FORGEJO_MCP_RESOURCE_AUDIENCE	resource-server モード：アクセストークンの aud に含まれている必要がある値（デフォルト：--resource の値）
--scopes-supported	FORGEJO_MCP_SCOPES_SUPPORTED	resource-server モード：メタデータおよび 401 チャレンジで公開するスコープをスペース区切りで指定します（デフォルトでは何も公開されません）
--forgejo-audience-claim	FORGEJO_MCP_FORGEJO_AUDIENCE_CLAIM	resource-server モード：呼び出し元の Forgejo Authorized Integration のオーディエンスを格納するアクセストークンのクレーム（デフォルト：forgejo_aud）
--forgejo-jwt-issuer	FORGEJO_MCP_FORGEJO_JWT_ISSUER	resource-server モード：サーバーが Forgejo 向け JWT に署名する際の発行者 URL。例：https://mcp.example.org/issuer。末尾にスラッシュのない https URL
--forgejo-jwt-signing-key-file	FORGEJO_MCP_FORGEJO_JWT_SIGNING_KEY_FILE	resource-server モード：Forgejo 向け JWT に署名する PEM 秘密鍵（EC P-256 または P-384、Ed25519、または 2048 ビット以上の RSA）
--forgejo-jwt-published-key-files	FORGEJO_MCP_FORGEJO_JWT_PUBLISHED_KEY_FILES	resource-server モード：鍵のローテーション用に、署名鍵とともに公開する PEM 鍵をカンマ区切りで指定します
--cli	-	CLI モードに入り、ツールを直接呼び出します
--user-agent	FORGEJO_USER_AGENT	HTTP User-Agent ヘッダー（デフォルト：forgejo-mcp/<version>）
-	FORGEJO_MCP_ALLOW_FILE_PATH_UPLOAD	file_path 添付ファイルのアップロードでホストのファイルシステムを読み取ることを許可します（1／true／yes／on。デフォルトでは無効です）
-	FORGEJO_MCP_UPLOAD_ROOT	file_path のアップロードをこのディレクトリ内に制限します（デフォルト：プロセスが読み取り可能な場所すべて）

コマンドライン引数は環境変数より優先されます。

passthrough モードでは resource-server の設定は拒否されるため、それらを設定しても --auth-mode resource-server を指定し忘れた場合、起動しません。

ホストファイルシステムから添付ファイルをアップロードする

create_issue_attachment、create_comment_attachment、create_release_attachment は、base64 の content または forgejo-mcp を実行しているマシン上の file_path を受け付けます。パス形式を使えば、大きなリリース成果物を MCP トランスポート経由で base64 に変換して送る必要がありません。

これはデフォルトで無効です。有効にすると、MCP クライアントを動かすものに、サーバープロセスが読み取れるあらゆるファイルを読み取る権限を与えることになります。プロンプトインジェクションを受けたエージェントが ~/.ssh/id_ed25519 を公開リリースアセットとしてアップロードする可能性もあります。意図して有効にし、可能な限りアクセス範囲を制限してください。

export FORGEJO_MCP_ALLOW_FILE_PATH_UPLOAD=1
export FORGEJO_MCP_UPLOAD_ROOT=/home/you/build/dist   # optional but recommended

FORGEJO_MCP_UPLOAD_ROOT を設定すると、絶対パス、..、シンボリックリンクのいずれかによって、そのディレクトリの外側に解決されるパスは、読み取り前に拒否されます。base64 の content によるアップロードには、どちらの変数も影響しません。

リリースの検証

リリースアーカイブには checksums.txt ファイルが付属し、プロジェクトのリリースキーペアを使って cosign で生成された checksums.txt.sig が任意で付属します。両方のファイルを検証すれば、ダウンロードしたバイナリがプロジェクトのリリースパイプラインでビルドされ、転送中に改ざんされていないことを確認できます。

ご注意ください： cosign による署名は 2026 年半ばに導入されました。署名の仕組みが組み込まれる前にリリースされたタグには .sig ファイルがありません。検証が適用されるのは v2.23.x 以降のみで、リリース時に COSIGN_PRIVATE_KEY シークレットが設定されている場合に限ります。

1. cosign をインストールする

お使いのプラットフォームに応じて、上流の cosign インストールガイド に従ってください。簡単な方法は次のとおりです。

# Linux/macOS — pinned binary
COSIGN_VERSION=v2.4.1
curl -sSfL -o /usr/local/bin/cosign \
  "https://github.com/sigstore/cosign/releases/download/${COSIGN_VERSION}/cosign-linux-amd64"
chmod +x /usr/local/bin/cosign

# macOS via Homebrew
brew install cosign

# Arch Linux
sudo pacman -S cosign

確認します。

cosign version

2. 公開鍵を取得する

cosign 公開鍵の正式な配布元は、 op1st-emea-b4mad GitOps リポジトリです。これは、リリースパイプラインが実行される op1st-pipelines 名前空間に cosign-signing-key-artifacts Secret をプロビジョニングする、唯一の信頼できる情報源でもあります。この鍵は、リリース成果物（checksums.txt.sig）に署名する成果物署名用の鍵で、以下の§5〜§6で使用するイメージ署名用の鍵 cosign-signing-key-images.pub とは別のものです。取得方法は 2 つあります。

ブランチ先端（最新の状態。今後の鍵のローテーションにも追従します）：

curl -sSfL -o cosign.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/branch/main/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-artifacts.pub

コミット固定（改ざんを検知できるため、CI／スクリプトに推奨）：

curl -sSfL -o cosign.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/commit/cd3715fa8283a2069a2e3e299744a7b55b1b0260/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-artifacts.pub

コミット固定のパーマリンクでは、コンテンツのハッシュが URL に含まれます。そのコミットのファイルが書き換えられると、ダウンロードに失敗するか、内容が一致しなくなります。自動化でこの鍵を使う前に、信頼できる最新のコミットに固定してください。

3. リリース成果物をダウンロードする

インストールしたタグ（例：v3.1.0）を選び、チェックサムファイル、その署名、バイナリアーカイブを取得します。

TAG=v3.1.0
VERSION="${TAG#v}"
BASE="https://git.b4mad.industries/agentic-forges/forgejo-mcp/releases/download/${TAG}"

curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_checksums.txt"
curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_checksums.txt.sig"
curl -sSfLO "${BASE}/forgejo-mcp_${VERSION}_linux_amd64.tar.gz"   # adjust os/arch

4. 署名を検証してから、チェックサムを確認する

cosign は、checksums.txt が cosign.pub と一致する秘密鍵の保有者によって署名されたことを検証します。チェックサムファイルを信頼できると確認したら、通常の sha256sum -c チェックでアーカイブの完全性を確認できます。

# Verify checksums.txt against the signature.
cosign verify-blob \
  --key cosign.pub \
  --signature "forgejo-mcp_${VERSION}_checksums.txt.sig" \
  "forgejo-mcp_${VERSION}_checksums.txt"
# Expected: "Verified OK"

# Verify the downloaded archive against the (now-trusted) checksums.
sha256sum --ignore-missing -c "forgejo-mcp_${VERSION}_checksums.txt"
# Expected: "<archive>: OK"

チェックサムの連鎖は、SBOM やアーカイブごとのその他のアセットも推移的に対象とします。checksums.txt を一度検証すれば、記載されているすべてのファイルを検証したことになります。

5. release-tools イメージの SLSA provenance を検証する

release-tools コンテナイメージ（Tekton リリースパイプラインで内部的に使用）は、Tekton Chains によって生成された SLSA v1.0 provenance を保持しています。このアテステーションは、イメージのダイジェストを、生成に使用された正確な PipelineRun、git コミット、およびビルダー ID に結び付けます。これにより、cosign 署名だけで証明できる範囲を超えたサプライチェーンの provenance を提供します。

cosign-signing-key-images の公開鍵を取得します（上記のアーティファクト署名鍵とは別の鍵です）。

curl -sSfL -o cosign-images.pub \
  https://codeberg.org/operate-first/op1st-emea-b4mad/raw/branch/main/manifests/applications/op1st-pipelines-tokens/cosign-signing-key-images.pub

特定のイメージタグに対してアテステーションを検証します。

IMAGE_TAG=v1.0.0   # substitute the release-tools tag you want to verify
cosign verify-attestation \
  --type slsaprovenance \
  --key cosign-images.pub \
  "codeberg.org/operate-first/release-tools:${IMAGE_TAG}" \
  | jq .

実行が成功すると、デコードされた in-toto ステートメント（JSON）が出力されます。predicate.buildDefinition.externalParameters.runSpec.params が想定される git リビジョンを参照していること、および predicate.runDetails.builder.id に Tekton Chains ビルダーが表示されていることを確認してください。

注： SLSA provenance アテステーションは、Tekton Chains のサポートが導入された forgejo-mcp-46j 以降のリリースで利用できます。それ以前のイメージタグには cosign 署名のみが含まれ、verify-attestation ペイロードはありません。

6. コンテナイメージを検証する

git.b4mad.industries/agentic-forges/forgejo-mcp アプリケーションイメージ（オプション D）は、release-tools イメージと同じ cosign-signing-key-images 鍵で署名され、CycloneDX SBOM が添付されており、Tekton Chains による SLSA v1.0 provenance を取得します。上記で取得した cosign-images.pub 鍵を再利用します。

署名を検証します。

IMAGE_TAG=v3.1.0   # substitute the release you are pulling
cosign verify \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq .

SLSA provenance アテステーションを検証します。

cosign verify-attestation \
  --type slsaprovenance \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq .

署名済み CycloneDX SBOM アテステーションを検証してダウンロードします。

cosign verify-attestation \
  --type cyclonedx \
  --key cosign-images.pub \
  "git.b4mad.industries/agentic-forges/forgejo-mcp:${IMAGE_TAG}" \
  | jq -r '.payload | @base64d | fromjson | .predicate' > forgejo-mcp.cdx.json

SBOM は、署名なしの attach sbom アーティファクトではなく、署名済みの in-toto アテステーション（cosign attest）になりました。cosign download sbom は使用できなくなりました。

公開パイプラインはダイジェストを使ってプッシュし、署名と SBOM の添付が成功した後にのみ vX.Y.Z / latest タグを付与するため、プルできるタグはすべて署名済みであることが保証されます。

検証に関するトラブルシューティング

• Error: no matching signatures — .sig ファイルが別のリリースのものか、cosign.pub が正しい鍵ではありません。同じタグから両方を再ダウンロードしてください。
• Error: cannot read file: checksums.txt.sig — リリースが cosign 署名の導入前のものか、その実行時にシークレットが未設定だったため署名がスキップされています。チェックサムのみの確認（sha256sum -c）に切り替えてください。これは転送中の破損は検出できますが、改ざんは検出できません。
• cosign.pub と署名の不一致 — リリース時に使用されていた鍵が含まれるコミットから公開鍵を取得したことを確認してください。不明な場合は、branch/main から取得してください。

トラブルシューティング

デバッグモードを有効にすると、詳細なログを確認できます。

forgejo-mcp --transport sse --url <url> --token <token> --debug

または、環境変数を設定します。

export FORGEJO_DEBUG=true

カスタム User-Agent： Forgejo インスタンスまたはプロキシがデフォルトの go-http-client ユーザーエージェントをブロックする場合は、カスタムのものを設定してください。

# Via environment variable
export FORGEJO_USER_AGENT="forgejo-mcp/1.0.0"

# Or via CLI flag
forgejo-mcp --user-agent "forgejo-mcp/1.0.0" --transport sse --url <url> --token <token>

ヘルプの利用

• 問題を報告 — バグ、質問、機能リクエスト
• セキュリティ上の問題を見つけましたか？ Issue トラッカーは使用しないでください。非公開で報告する方法については、SECURITY.md を参照してください。
• ソースコードを表示
• Matrix でチャット — #forgejo-mcp:b4mad.net

このリポジトリは、ピアツーピアのコードコラボレーションネットワークである Radicle にもミラーされています。次のコマンドでクローンできます。

rad clone rad:z4PdPpsH9iJQcWfqTbxpFcWaZ9zPL

開発者向け

ビルド手順、アーキテクチャの概要、コントリビューションガイドラインについては、DEVELOPER.md を参照してください。

既知の問題

• 古い Codeberg モジュールパスからのインストール — go install codeberg.org/goern/forgejo-mcp/v2@latest は読み取り専用ミラーを参照して引き続き解決されますが、そのミラーの内容は現在のリリースより遅れています。代わりに git.b4mad.industries/agentic-forges/forgejo-mcp/v3@latest を使用してください。

  以前は、新しいパスは、名前を変更した go.mod を含むリリースが出るまでインストールできないと記載していました。そのリリースはすでに公開されています — v3.0.0 以降では module git.b4mad.industries/agentic-forges/forgejo-mcp/v3 が宣言されているため、新しいパスから通常どおりインストールできます。以前あった replace ディレクティブによる阻害要因（#67）も解消されており、go.mod にその記述はありません。

コントリビューター

forgejo-mcp は、課題の報告、コードの作成、PR のレビュー、プロジェクトの推進に携わる皆さんによって形作られています。皆さん、ありがとうございます。🙏

コードコントリビューター

貢献者	主な貢献
goern (Christoph Görn)	プロジェクトの作成者およびメンテナー
Ronmi Ren	共同作成者。SSE/HTTP トランスポート、課題のブロック、CI/CD の改善、ロゴ、Glama 仕様
twstagg (Tristin Stagg)	ユーザーエージェント設定のサポート（PR #89）
mattdm (Matthew Miller)	ロギングの改善、FORGEJO_* への移行、README、URL のリファクタリング
byteflavour	check_notifications と通知管理 API 全般（PR #84、#86）。HTTP/SSE トランスポート向けのリクエストごとのステートレス認証（PR #138）。NixOS のインストール手順（PR #146）。ネットワークトランスポートの強化 — デフォルトでループバックにバインド、Host/Origin のチェック、リクエストごとの認証情報（PR #545、#573 としてマージ。#586、#585、#589）。OAuth リソースサーバーモード — インバウンド JWT の検証と、Forgejo 16 Authorized Integration の署名によるアウトバウンド通信。運用者向けおよびユーザー向けガイドと、アンカー付きのデモシナリオ 40 件を含む（PR #584、#582 で調査）。開発環境用の FORGEJO_MCP_EXEC（PR #580）。機能リクエスト #80、#85
jesterret	プルリクエストのレビューとコメントのサポート（PR #51）
appleboy	カスタム SSE ポートのサポート、バグ修正
ignasgil	remove_issue_labels ツール（PR #96）
dmikushin (Dmitry Mikushin)	MCP クライアントから渡される文字列形式の数値パラメーターの解析を修正（PR #93）
jiriks74	mcp-go v0.44.0 への依存関係の更新（PR #90）
th (Tomi Haapaniemi)	update_pull_request ツール
hiifong	初期のバグ修正と更新
Lunny Xiao	初期の貢献
techknowlogick	初期の貢献
yp05327	初期の貢献
mw75	リポジトリ作成時のオーナー／組織サポート（PR #18）
Dax Kelson	課題コメントの管理（PR #34）
Guruprasad Kulkarni	Arch Linux AUR のインストール手順（PR #69）
Mario Wolff	貢献
Massimo Fraschetti	貢献
synath (David Paul Turley)	ServerVersion プローブによるリポジトリスコープのトークンサポート（PR #112）。マージ時のステータスコードチェック（PR #113）。Claude Desktop Extension（.mcpb）のパッケージ化（PR #118、#123）。課題の due_date とサーバー側ソート（PR #483）。上限付きの課題一覧およびコメントスレッドのリソース（PR #487）。X-Total-Count に基づくページネーション付きエンベロープの total_count（PR #507）。create_*_attachment のタイムアウト強化（PR #534、#536）。リポジトリをまたぐ課題の依存関係（PR #535）
BrilliantKahn	get_file_content のデフォルトをプレーンテキストに変更（PR #116）。list_repo_contents および get_repo_tree ツール（PR #117）。オープンソースへの初めての貢献 — ようこそ！🎉
nesvet (Eugene Nesvetaev)	get_repo/edit_repo（PR #527）。リポジトリトピックのツール（PR #528）。Actions 実行のキャンセル／削除と実行アーティファクト（PR #533）。get_commit_statuses（PR #542）。パッケージの一覧表示／取得／削除／ファイルのツール（PR #543）。課題の作成、割り当て、置換でラベル名を指定可能に（PR #591）。ラベルの作成、編集、読み取りで exclusive と is_archived を指定可能に（PR #592）
pisco (Marco Pisco)	課題、コメント、リリースの添付ファイルを file_path からアップロード。ストリーミング形式のマルチパート処理により、大きなリリースアセットを Base64 経由で往復させる必要がなくなりました（PR #481）
paulgit (Paul Git)	すべてのツールに正確な MCP アノテーションとタイトルを宣言し、分類基準を DEVELOPER.md に記載（PR #633、#602 を置き換え）
derliebemarcus (Marcus Pauli)	change_files による複数ファイルのアトミックなコミットと、create_file/update_file におけるバイナリーセーフな content_base64（PR #628）。apply_diff_patch によるネイティブな差分パッチの書き込み（PR #629）
MaherMakerHallerErne (Maher Al Sairawan)	課題の依存関係ツール — list_issue_dependencies、list_issue_dependents、add_issue_dependency、remove_issue_dependency — Forgejo API の正しい仕様に準拠（PR #335）
woozar (Johannes Herrmann)	直接 REST API 経由の Wiki サポート — ページの一覧表示／取得／作成／更新／削除とリビジョン。強化された仕様とページネーションを含む（PR #379）
dismantl (Dan Staples)	上限付きの Forgejo v16 以降のワークフロージョブログ — list_action_run_jobs、get_action_job_logs（PR #378）
matheusalves96 (Matheus Alves)	リポジトリおよび組織の Actions シークレット用ツール — 一覧表示、作成または更新、削除（PR #605）

コミュニティの貢献者

プロジェクトの方向性を形作った、課題の報告者とディスカッションの参加者です。

貢献者	貢献内容
byteflavour	#80（マイルストーン／ラベルの検出）、#85（通知 API の提案）を報告。ディスカッションで積極的にレビュー
choucavalier	#82（スキルの修正）、#70（macOS arm64 リリース）、#62（バイナリリリースと mise のサポート）を報告
MalcolmMielle	#59（PR レビューツール — その後実装済み）を報告
redbeard	#60（Actions のサポート — その後実装済み）を報告
c6sepl6p	#72（base64 エンコード）、#54（プルリクエストのマージ — その後実装済み）を報告
malik	#73（バージョンフラグ）、#47（Nix ビルドの修正）を報告
a2800276	#74（OpenAI との互換性）を報告
simenandre	#49（go install のサポート）を報告
BasdP	#42（Projects のサポート）を報告
BoBeR182	#32（wiki のサポート）を報告
ignasgil	#95（remove_issue_labels の機能リクエスト）を報告
Vokuar	#99（ストリーミング可能な HTTP トランスポートのサポート）を報告
janbaer	#98（レビューコメントへの返信）を報告
fraschm98	初期の課題報告
heathen711	#106（課題／コメントへの添付ファイル — その後実装済み）を報告。1 MiB のインライン上限と browser_download_url へのフォールスルー設計に貢献
decarvalhoaa (Antonio De Carvalho)	Open WebUI の背後で実際にコンテキストウィンドウがあふれた経験をもとに、#593（サーバー側の応答サイズ上限）を報告。#596 の list_repo_pull_requests ペイロード対応のきっかけとなった測定結果も提供
chris420 (Chris Oloff)	#452（組織全体の課題検索 — その後 search_issues として実装）を報告。次ページの確認処理をインスタンス上限の適用に置き換えた PR #458 の設計レビューを行い、応答エンベロープが自身の limit を誤って報告していることも指摘

サイボーグ貢献者

このプロジェクトには、AI コーディングエージェントからの貢献もありました。通常の PR として提出され、人間がレビューしています。

エージェント	役割	貢献内容
brenner-axiom (b4-dev, B4arena)	AI 開発エージェント	組織管理ツール（PR #94）、showboat のデモ（PR #97）、list_repo_milestones および list_repo_labels ツール（PR #83）、競合状態の修正（PR #78）、貢献者向けドキュメント（PR #87、#88）を作成。#76 を報告し、コードレビューも実施
opencode	AI 開発エージェント	プルリクエストのレビューとコメントのサポート（PR #51）
claude-code	AI 開発エージェント	BrilliantKahn と共同で、get_file_content のプレーンテキストをデフォルトに設定し、list_repo_contents／get_repo_tree ツールを追加（PR #116、#117）
b4mad-release-agent	リリース自動化	変更履歴の作成とリリースタグ付けを自動化
the #B4mad Renovate bot	依存関係の更新	依存関係のアップグレードを自動化

貢献してみませんか？課題またはプルリクエストを作成してください。どなたでも歓迎します。

ライセンス

このプロジェクトはオープンソースです。ライセンスの詳細については、リポジトリをご覧ください。