CircleCI
Claude Codeに渡せる権限の範囲と、つなぎ方を、公式の資料から読み取れる範囲でまとめました。
← ラボ / Claude Code ガイド / 連携台帳
Circle Internet Services, Inc.・開発ツール・CI/CD・海外 公式サイト
ビルド・テスト・デプロイを自動化するCI/CDのクラウドサービス(Server版の自社運用もある)。ワークフローはconfig(YAML)で定義する。
Claude Codeに、どこまで権限を渡せるか
- 読み取り専用で渡せるか 未確認
- 公式MCPの両ページ(ホスト型・CLI版)に読み取り専用モードの記載はない。トークン側では、プロジェクトAPIトークンに「Status」(ビルド状況の読み取り)と「Read Only」(読み取りのみ。ただしv1 APIのみ)の範囲があると公式に記載。一方、Webアプリで手動作成する個人APIトークンは「フル読み書き」と記載。OAuthで作成されたトークンは認可時に選ぶ Read/Write/Admin の権限になる、との記載があるが、ホスト型MCPのOAuthがこの選択に対応するかは記載なし。v2 APIやMCPに読み取り専用トークンを渡せるかは確認できなかった。
- 権限(スコープ)を選べるか あり
- プロジェクトAPIトークンは特定プロジェクト単位で、Status/Read Only(v1のみ)/Admin(v1のみ、読み書き)の3種。個人APIトークンは手動作成だとフル読み書きで範囲指定なし。MCPのOAuth/トークンのスコープはホスト型接続ページに記載なし。
- 危険な操作の既定
- ホスト型MCPにrerun_workflow・cancel_workflowがあり、既定の無効化や読み取り専用の記載はない。概要ページには、これらの操作を確認前に見直すよう促す記載がある(アクセス制御の仕組みではない)。CLIの削除系コマンドの確認プロンプトの有無は未確認。
- 削除ができるか できる
- 【API】コンテキスト(中の環境変数ごと)、プロジェクト、チェックアウトキー、環境変数、トリガー、スケジュール、Webhook、組織、パイプライン定義など。【CLI】コンテキスト、シークレット、環境変数、証明書、ネームスペース、signing-config。ホスト型MCPには削除ツールの記載なし。
- 取り消し方(キー・接続)
- 個人APIトークン: User settings > Personal API Tokens の Remove 列のXをクリックして確認。プロジェクトAPIトークン: Project Settings > API Permissions で Remove 列のXをクリックし、DELETEと入力して Delete API Token。トークンは作成後に変更できず、削除して作り直す(ローテーション)。個人トークンは有効期限を最大1年先まで設定できる。ホスト型MCPのOAuth2アクセスの取り消し手順は公式の取得ページに記載なし(CircleCI側で取り消し・ローテーションできるとだけ記載)。
つなぎ方(公式の資料にある範囲)
公式MCP あり
CircleCIが運営するホスト型MCPサーバー(https://mcp.circleci.com/v1/mcp)。公式の概要ページに載るツール: hello、list_runs、get_run、list_workflows、get_workflow、list_jobs、get_job、get_job_logs、list_artifacts、list_job_tests、download_usage_data(いずれもCIの状態を変えない)と、rerun_workflow(ワークフローの再実行、失敗ジョブだけも可)、cancel_workflow(実行中ワークフローのキャンセル)(この2つはCIの状態を変える)。ホスト型のツール表(13個)にはパイプラインのトリガーとロールバックのツールがない(ページに明示した文はなく、表に載っていないということ)。概要ページには「Review destructive actions before confirming」「Rerunning or canceling a workflow changes real CI state, so check what your assistant is about to do first」とあるが、サーバー側の確認機能の記載ではない。別系統として、CircleCI CLIに組み込みのMCP(circleci mcp、ローカルで動作)があり、CLIのコマンドをツールとして公開(設定の作成・検証、組織とプロジェクトの管理、orb、ポリシー、セルフホストランナー、iOSコード署名、デプロイ追跡、Docker Layer Cache、API直接呼び出し)。ページの例にはプロジェクトの環境変数の一覧、orbの公開、Docker Layer Cacheのパージがある。旧来のnpx版ローカルMCP(@circleci/mcp-server-circleci。run_pipeline、rerun_workflow、run_rollback_pipelineなど)は非推奨で、リポジトリのREADMEに「deprecated」「アーカイブ予定」とある。
つなぎ方(公式の記載)
ホスト型(公式ページの記載): claude mcp add --transport http circleci-mcp-server https://mcp.circleci.com/v1/mcp を実行し、Claude Code内で/mcp > circleci-mcp-server > Authenticate でOAuth2サインイン。個人APIトークンを使う場合は同コマンドに --header "Authorization: Bearer <your-circleci-token>" を付ける。CLI版はClaude Code向けの手順が当該ページになく、circleci mcp start(stdio)/circleci mcp stream(HTTP)で起動できるとの記載まで。
公式CLI あり
CircleCI CLI(リファレンス: cli.circleci.com/reference)。コマンド群: artifact、config、job、pipeline、run、testresult、workflow、certificate、component-version、context、deploy、dlc、envvar、migrate、namespace、orb、org、policy、project、runner、signing-config、auth、mcp、api など。削除系として context delete(「Delete a CircleCI context by UUID or name」)、context secret delete、context restriction delete、certificate delete、envvar delete、namespace delete、signing-config delete が確認できた。dlc purge(キャッシュのクリア)、workflow cancel、run cancel もある。pipeline run(「Trigger a new pipeline run」)、run trigger、project trigger でパイプラインを起動できる。認証はcircleci auth login、またはCIRCLE_TOKEN環境変数。
公式API あり
CircleCI API v2(v3も案内あり。ページに「Start with the V3 API - it's where new capabilities are landing」、v2も引き続きサポート)。認証は、ヘッダー(Circle-Token)・Bearer・Basic・クエリの4方式がページに列挙。削除系エンドポイント: コンテキスト(中の環境変数ごと)、コンテキストの環境変数・制限、プロジェクト、チェックアウトキー、プロジェクトの環境変数、トリガー、スケジュール、アウトバウンドWebhook、組織、パイプライン定義、グループ、OTLPエクスポーター、OIDCクレーム、URL Orbの許可リスト。パイプラインのトリガーAPI(旧エンドポイントは非推奨、新しい方はパイプライン定義IDで起動)とプロジェクトのロールバックAPIがある。レート制限超過は429。
第三者製MCP(公式ではない) 2件
- ampcome-mcps/circleci-mcp(作者: ampcome-mcps(GitHub組織))
書き込み・削除: あり(READMEにパイプライン実行 run_pipeline、ロールバック実行 run_rollback_pipeline、ワークフロー再実行 rerun_workflow の記載。キャンセル・削除は記載なし)
READMEは「CircleCI向けMCPサーバーを提供」とし、CursorやWindsurfなどから自然言語で使えると説明。インストール手順やnpmパッケージ名は CircleCI 公式リポジトリのものと同じ表記で、公式READMEに近い内容。最終更新日はページに表示なし。
https://github.com/ampcome-mcps/circleci-mcp - nickbrett1/circleci-mcp(作者: nickbrett1(GitHub個人アカウント))
書き込み・削除: 記載なし(READMEは個別ツールを列挙していない)
READMEは Open WebUI 向けにまとめたMCPサーバー集と説明。circleci(CircleCI公式CLIのMCPを起動、約150ツール)、circleci-cost(利用量・実行履歴、4ツール)、circleci-lite(実行状況・ログ、3ツール)の3種。最終更新日はページに表示なし。
https://github.com/nickbrett1/circleci-mcp
第三者製のMCPは、サービスの運営元が作ったものではありません。作者と中身を確かめてから使うかどうかを決めてください。ここに載せているのは、公式のレジストリやGitHubで見つかったものを、書かれている範囲でまとめたもので、おすすめではありません。
探した場所(6件)
- WebSearch(CircleCI MCP関連)。検索結果は主にcircleci.com内で、第三者製MCPの検索は今回行っていない
- WebSearch: CircleCI MCP server github unofficial
- WebSearch(github.com限定): circleci-mcp-server
- https://github.com/nickbrett1/circleci-mcp
- https://github.com/ampcome-mcps/circleci-mcp
- registry.modelcontextprotocol.io は取得エラーで開けず、GitHub検索ページはアクセス不可
できる操作
読み取りでできる操作
- 【MCP】ホスト型: 実行(run)・ワークフロー・ジョブの一覧と詳細、ジョブのログ(失敗ステップが既定)、成果物の一覧、テスト結果、組織の利用状況CSVの書き出し
- 【CLI】config検証、job/pipeline/workflowの参照、envvar・contextの一覧など(コマンド別の詳細は未取得)
- 【API】パイプライン・ワークフロー・ジョブ・成果物などの取得
書き込みでできる操作
- 【MCP】ホスト型: rerun_workflow(再実行)、cancel_workflow(キャンセル)。CLI MCP: CLIのコマンド全般(orbの作成・公開など)
- 【CLI】pipeline run/run trigger/project trigger によるパイプライン起動、orbの公開、環境変数・コンテキストの更新(コマンドの詳細は一部未取得)
- 【API】パイプラインのトリガー、プロジェクトのロールバック、各種設定の作成・更新
管理者操作(削除・課金・設定変更など)
- 【MCP】ホスト型には削除系ツールの記載なし。CLI MCPはCLIのコマンドをツール化するため、CLIの削除系(context delete、envvar delete、namespace delete、certificate delete、dlc purge等)にも届くはずだが、各ツールの扱いは当該ページに記載なし(未確認)
- 【CLI】コンテキスト・シークレット・環境変数・証明書・ネームスペース・signing-configの削除、Docker Layer Cacheのクリア。確認プロンプトの有無は取得できた範囲では記載なし
- 【API】コンテキスト(中の環境変数ごと)・プロジェクト・チェックアウトキー・環境変数・トリガー・スケジュール・Webhook・組織・パイプライン定義などの削除
制限
- ホスト型MCPのプラン要件・ベータ/GAの別は、概要ページに記載なし
- 旧npx版MCP(@circleci/mcp-server-circleci)は非推奨。ホスト型またはCLI MCPへの移行を案内。両方の導入前に旧版の削除が必要と記載
- API v2の呼び出しは429で制限(具体的な回数の記載なし)。トリガーAPIの新エンドポイントは対応する設定ソース(GitHub App/GitHub Server/GitHub OAuth/Bitbucket DC/Bitbucket OAuth)が限られる
- ホスト型MCPはワークフローの再実行とキャンセルができる。公式に既定の確認の仕組みの記載はなく、再実行が課金(クレジット消費)に関わるかは、MCPページには記載がない(料金ページにはクレジット制の記載)
- CLI MCPはCLIの削除系コマンドをツールとして公開する。コンテキストの削除は中の環境変数ごと消える(API説明)。復元の記載なし
- 手動作成の個人APIトークンはフル読み書き権限。MCPにこれを渡すと書き込みと削除に届く可能性がある(権限を絞る手段は上記のとおり限定的)
- 個人APIトークンはパスワードと同様に扱い、環境変数やシークレットストア経由で渡すよう公式ページが案内
認証・料金・日本語・実機検証
- 認証方式
- 【MCP】ホスト型はOAuth2(推奨、既存のCircleCIアカウントでサインイン)または個人APIトークン(Authorization: Bearer)。CLI MCPは circleci auth login またはCIRCLE_TOKEN。【API】個人APIトークン、プロジェクトAPIトークン、OAuth。
- 公表されている料金(2026年10月16日確認)
- Free 月額$0(月30,000クレジット、アクティブユーザー最大5人)、Performance 月額$15〜(月払いまたは前払いクレジット。30,000クレジットと5ユーザー込み)、Scale は価格非掲載(問い合わせ、年払い)、Server は当該ページに価格なし。通貨はページに明記なし($表記のみ。税別と記載)。Freeの欄に「6,000 build minutes」(分)の記載があり、FAQの換算(30,000クレジット=3,000分、Linux Medium、10クレジット/分)と食い違っており、ページ内の数字に不整合がある。2026年10月16日確認。 料金ページ
- 日本語対応
- あり。ドキュメントに日本語版がある(https://circleci.com/docs/ja/ を開いて確認。ただし一部の節は英語のまま)。Webアプリ(管理画面)の日本語対応は公式の取得ページに記載がなく未確認。
- Claude Code実機検証
- 未検証(この台帳は、動かして確かめた記録ではありません。Akiraが試したときは、検証日つきで書き換えます)
確認できていない点(8件)
- CLIリファレンスの末尾約1.8万字、各削除コマンドの確認プロンプトの有無
- CLI MCPの個別ツール一覧と、読み取り専用で使う方法(circleci mcp tools の出力は未取得)
- ホスト型MCPのOAuthスコープ・取り消し手順、プラン要件、ベータ/GA
- API v2が読み取り専用トークンを受け付けるか、トークンのスコープ(APIページに記載なし)
- Webアプリ(管理画面)の日本語対応、Serverプランの価格
- 第三者製MCP(今回は検索していない)
- 旧npx版READMEの最終リリース日(Releasesが空)
- 2026-10-17再確認で残った点: permission.read_only: CircleCIのトークン管理ページ・ホスト型MCPページは取得エラー(URL推測が外れた)で読めず、確認できなかった
出典(11件)
- CircleCI MCP overview(CircleCI)(確認日 2026-10-16)
- Connecting to the CircleCI MCP server(CircleCI)(確認日 2026-10-16)
- Connecting to the CircleCI CLI MCP(CircleCI)(確認日 2026-10-16)
- mcp-server-circleci README(CircleCI-Public)(確認日 2026-10-16)
- CircleCI CLI Reference(CircleCI)(確認日 2026-10-16)
- CircleCI API v2(CircleCI)(確認日 2026-10-16)
- Managing API tokens(CircleCI)(確認日 2026-10-16)
- Pricing(CircleCI)(確認日 2026-10-16)
- ドキュメント日本語版(CircleCI)(確認日 2026-10-16)
- ampcome-mcps/circleci-mcp README(GitHub)(確認日 2026-10-17)
- nickbrett1/circleci-mcp README(GitHub)(確認日 2026-10-17)
この台帳は、公式の資料を読んだ範囲のことで、動かして確かめたものではありません。確認日: 2026年10月16日。
ラボの資料は、公式の文書を読んでまとめたもので、実際に使って確かめた記録ではありません。日付や仕様は変わるので、使う前に各ページの出典で確かめてください。事実と「僕らの見立て」は、分けて書いています。