CircleCI が単体で提供していた MCP サーバー（standalone MCP server、@circleci/mcp-server-circleci）は非推奨になりました。セキュリティ勧告 GHSA-8xjg-jpfh-5257 が発行され、CircleCI cloud を利用している場合は CircleCI CLI に組み込まれた MCP サーバーへの移行が推奨されています。

この記事では、macOS + Homebrew にて移行を行う方法を紹介します。

CircleCI MCP を整理する

CircleCI は AI アシスタント向けに MCP サーバーを 2 種類提供しています。非推奨になったバージョンも含めて表に整理しました。

種類	動作場所	認証	状態
単体版 MCP サーバー（`@circleci/mcp-server-circleci`）	ローカル（stdio）	Personal API Token	非推奨
CLI 組み込み MCP	ローカル（stdio）	CLI のセッション（OAuth）	移行先（本手順の対象）
ホスト型 MCP サーバー	クラウド（HTTPS）	OAuth またはPersonal API Token	本記事では紹介しない

公式ドキュメントは、CLI 組み込み MCP がマシン上のローカルプロセスとして動作し、circleci auth login または CIRCLE_TOKEN の認証情報を使うと説明しています。一方ホスト型は CircleCI が運用するリモートサーバーで、AI アシスタントが HTTPS 経由で接続します。両者は独立していて、片方に接続してももう片方は切断されません（CircleCI MCP overview）。

移行を始める前に、次の前提を確認してください。

対象は CircleCI cloud の利用者です。CircleCI Server を利用している場合、または事情により移行できない場合は、公式アナウンスどおり単体版を 0.19.0 に更新して据え置きます
CircleCI CLI v1 は preview です。公式ドキュメントにも、この段階では利用可能なコマンドや機能が変わりうると明記されています（The CircleCI CLI）。本番運用の自動化スクリプトに組み込む場合は、コマンド名やフラグが変わる前提で追従できる形にしてください。掲載している出力は 2026 年 7 月時点の macOS + Homebrew 環境、CLI 1.0.45783-pre で確認したものです。バージョンやメッセージ文言は更新により変わる場合があります
レガシー版の CircleCI CLI（v0.1.x）を Homebrew で導入している場合、preview 版を入れる前にアンインストールが必要です。公式リポジトリの README にも導入手順の前段として記載されています（circleci-cli README）

MCPサーバーを移行する

MCPサーバーの新旧移行は、次の4つの手順で行います。

旧設定を撤去し、レガシー CLI をアンインストールする
preview 版 CLI を導入し、切り替わりを確認する
OAuth でログインする
MCP サーバーを有効化し、クライアントに反映する

1. 旧設定を撤去し、レガシー CLI をアンインストールする

AI アシスタント側に登録した MCP サーバーを削除し、Homebrew 側のレガシー CLI をアンインストールします。

旧 MCP サーバーの削除は、クライアントごとに宛先が違います

公式アナウンスは、クライアントごとに削除手順を分けて案内しています。

Claude Code: claude mcp remove circleci-mcp-server を実行する
Claude Desktop: 設定画面の Edit Config から claude_desktop_config.json の該当ブロックを削除する

Claude Desktop 側に登録された旧サーバーを消そうとして Claude Code のコマンドを実行すると、対象が見つからずに終了します。

% claude mcp remove circleci-mcp-server
No MCP server named "circleci-mcp-server". Run `claude mcp add` to add one.

claude mcp remove が参照するのは Claude Code の設定であり、Claude Desktop の claude_desktop_config.json には届きません。Claude Desktop に登録している場合は、設定ファイルを直接編集して該当ブロックを削除してください。

レガシー CLI のアンインストールを先に済ませます

preview 版 CLI は Homebrew の cask として配布されます。一方レガシー版は homebrew-core の formula です。両者は circleci という同じ名前のバイナリを置くため、Homebrew はこの衝突を自動で解決できません。

そのため、preview 版を入れる前に次を実行します。

brew uninstall circleci

このステップを飛ばすと、cask の導入自体は成功する一方でバイナリのリンクが貼られず、旧バージョンが実行され続けます。

2. preview 版 CLI を導入し、切り替わりを確認する

導入は 1 コマンドで完了します。ただしレガシー版が残っていると、パッケージは入るのにバイナリが有効化されません。

コマンドは 1 行で実行します

brew install circleci-public/circleci/circleci@next

インストール成功と、有効化は別です

レガシー版が残った状態で導入すると、次の出力が返ります。

==> Installing Cask circleci@next
Warning: It seems there is already a Binary at '/opt/homebrew/bin/circleci' from formula circleci; skipping link.
...
🍺  circleci@next was successfully installed!

最終行は成功を示していますが、skipping link の警告が出ています。/opt/homebrew/bin/circleci にレガシー版のバイナリが残っているため、Homebrew は衝突を避けてリンクを貼らずに終了しました。この状態で circleci を実行すると、preview 版ではなくレガシー版が動きます。

caveats にも同じ趣旨の案内が出ます。

This preview build installs a `circleci` binary that conflicts with the
stable `circleci` formula from homebrew-core. Homebrew cannot declare a
cask/formula conflict automatically, so if you have the core formula
installed, unlink it first to avoid a clashing symlink:

  brew unlink circleci

リンクはインストール時にスキップされているため、レガシー版を外したうえで cask 側を貼り直します。

brew uninstall circleci
brew reinstall circleci-public/circleci/circleci@next

貼り直しに成功すると、警告ではなくリンクのログが出ます。

==> Installing Cask circleci@next
==> Linking Binary 'circleci' to '/opt/homebrew/bin/circleci'
==> Linking Manpage 'circleci.1' to '/opt/homebrew/share/man/man1/circleci.1'
🍺  circleci@next was successfully installed!

バージョンで切り替わりを確認しましょう

circleci version

preview 版が有効になっていれば、-pre を含むバージョンが返ります。

circleci 1.0.45783-pre (a6910dfdee79)

レガシー版が動いている場合は 0.1.x 系が返ります。レガシー版の formula が残っていないかは brew info でも確認できます。

brew info circleci

homebrew-core 側の formula の状態が表示されます（出力は抜粋）。

==> circleci ✘: stable 0.1.38646 (bottled), HEAD
Enables you to reproduce the CircleCI environment locally
https://circleci.com/docs/guides/toolkit/local-cli/
Not installed

Not installed と表示されていれば、レガシー版の formula は削除済みです。Installed と出る場合はアンインストールが完了していないため、brew uninstall circleci に戻ってください。

3. OAuth でログインする

preview 版 CLI はブラウザ経由の OAuth でログインします。個人 API トークンを生成してシェルの環境変数に置く必要がなくなり、認証情報は OS のキーチェーンに保存されます。

circleci auth login

対話的に接続先と認証方式を選びます。

? Where do you use CircleCI?
› circleci.com
  Other

? How would you like to authenticate circleci.com?
› Login with a web browser
  Paste an authentication token

ブラウザで認可画面が開きます。ログイン中のアカウントと、CircleCI CLI がアカウントへのアクセスを求めていることが表示されます。

Allow を選ぶと認可が完了し、ターミナルに戻るよう案内されます。

ターミナル側には保存先も出力されます。

✓ Authentication complete.
✓ Logged in as <アカウント名>.
✓ Saved token to keyring
✓ Saved host to /Users/<ユーザー名>/.config/circleci/config.yml

トークンは keyring に、接続先ホストは ~/.config/circleci/config.yml に保存されます。設定ファイルにトークンが平文で書かれないため、旧構成のようにトークンをファイルへ貼り付ける手順は消えます。

ログイン状態は circleci auth me で確認できます。

   User

  • ID: <ユーザー ID>
  • Name:
  • Login: <アカウント名>
  • Avatar URL: https://avatars.githubusercontent.com/u/<ID>?v=4

Login に自分のアカウント名が表示されれば、認証情報は有効です。

4. MCP サーバーを有効化し、クライアントに反映する

有効化のコマンドは AI アシスタントごとに用意されています。ここでは Claude Desktop で有効化し、その設定を Claude Code に取り込みます。

Claude Desktop に登録します

Claude Desktopに MCPサーバーを登録するには、以下のコマンドを実行します。

circleci mcp claude enable

実行すると、設定ファイルのバックアップを作成したうえでサーバーが登録されます。

Using config path "/Users/<ユーザー名>/Library/Application Support/Claude/claude_desktop_config.json"
Backing up config file at "/Users/<ユーザー名>/Library/Application Support/Claude/claude_desktop_config.backup.json"
Successfully enabled MCP server: "circleci-cli"
  Command: /opt/homebrew/bin/circleci
  Args: [mcp start]

Command はローカルに導入した CLI のバイナリで、Args は mcp start です。つまり Claude Desktop は手元の CLI を MCP サーバーとして起動します。

無効化する場合は enable を disable に置き換えます（CLI Reference: MCP）。

Cursor: circleci mcp cursor enable
VS Code: circleci mcp vscode enable

Claude Code へ取り込みます

circleci mcp claude enable が書き込むのは Claude Desktop の設定です。Claude Code でも使う場合は、Claude Desktop の設定を取り込みます。

claude mcp add-from-claude-desktop -s user

実行すると Claude Desktop に登録されているサーバーの一覧が表示され、取り込む対象を選択できます。他の MCP サーバーを併用している場合はすべて候補に出るため、この手順で追加した circleci-cli だけを選びます。

取り込み後、Claude Code の MCP 管理画面で状態を確認できます。手元の環境では次のように表示されました。

   Circleci-cli MCP Server
   Status:           ✔ connected
   Command:          /opt/homebrew/bin/circleci
   Args:             mcp start
   Config location:  /Users/<ユーザー名>/.claude.json
   Capabilities: tools
   Tools: 141 tools

旧MCPサーバーの設定を片付ける

バックアップファイルは不要になりますので、作成されたclaude_desktop_config.backup.json は削除しておきましょう。

もしJSONファイルにCircleCIのPersonal Access Tokenを定義していた場合は、念のためトークンを無効化しておくと良いでしょう。User Settings の Personal API Tokens から該当トークンを削除します（Managing API Tokens）。失効させておけば、バックアップファイルなどにコピーが残っていても使われません。

おわりに

単体版 MCP サーバーから CLI 組み込み MCP への移行は、コマンド自体は 4 つの手順です。実機で止まった 4 か所はいずれも、レガシー版 CLI が残っていたか、コマンドの宛先を取り違えたかのどちらかでした。circleci version の出力を確認しながら進めれば、どちらなのか判別できます。

旧構成で使っていたトークンの失効まで済ませれば、移行は完了です。

CLI v1 は preview 版であるため、動作に差異を見つけた場合は circleci-cli の Issue から報告できます。