Claude CodeのFigma MCPが動かない・403で繋がらない時の原因と直し方【2026年版】
Figma Dev Mode MCP Serverの403エラー・Invalid sessionId・削除できないゾンビ接続を症状別に切り分ける。リモート/デスクトップサーバーの要件差を公式ドキュメントとGitHub Issue実例つきで整理した。
エンジニアのゆとです。
FigmaのMCPサーバーをClaude Codeに繋いで「デザインを直接参照させて実装する」ワークフローを試そうとした人が、そこそこの確率で最初の一歩でつまずいている。/pluginから入れたはずなのに403が返ってくる、claude mcp listではConnectedなのにツールを呼ぶとInvalid sessionIdで落ちる、直そうとして一度削除しようとしたらInvalid server ID formatと言われて削除すらできない——検索するとセットアップ手順の記事はたくさん出てくるのに、動かなくなったときにどう切り分けるかを書いた記事がほとんど見当たらなかった。
FigmaのフォーラムとAnthropicのGitHub Issueを漁ると、同じ症状の報告がいくつも見つかる。この記事では設定手順そのものは最小限にして、「繋がらない・動かない」の原因を症状別に整理する。
結論 — 症状別の原因早見表
| 症状 | 主な原因 |
|---|---|
403 Forbiddenが返る | Figmaのシートがデスクトップサーバーの要件（Dev/Fullシート・有料プラン）を満たしていない、またはOAuthトークンが失効している |
ツールは並ぶが呼ぶとInvalid sessionId（-32001） | 古い手順を参考にして/sseエンドポイントやtype: "sse"のまま設定している |
claude mcp listでFailed to connectのまま | Figmaデスクトップアプリ側のローカルブリッジ（ポート3845）がセッションを失っている |
削除しようとするとInvalid server ID formatで止まる | .mcp.jsonや~/.claude.jsonにfigmaとfigma-desktopが重複登録されている |
| 繋がっているが返答が異常に遅い | 大きいデザインファイル全体を参照させていて、裏で大量のツール呼び出しが走っている |
claude plugin install自体が失敗する | 組織の管理設定でプラグインインストールがブロックされている |
まずは自分がどのパターンかをclaude mcp listと/mcpパネルで確認するところから始める。
前提 — リモートサーバーとデスクトップサーバーは別物
Figma MCPには「リモートサーバー」と「デスクトップサーバー」の2種類があり、これを混同したまま設定しているケースが多い。
リモートサーバー（https://mcp.figma.com/mcp）は全プラン・全シートで利用できる。公式が推奨しているのもこちらで、セットアップはClaude Codeの公式プラグイン経由が最短だ。
claude plugin install figma@claude-plugins-officialインストール後にClaude Codeを再起動し、/pluginコマンドでプラグインマーケットプレイスを開く。「Installed」タブからfigmaを選んでEnterを押すと認証ページが開くので、そこでAllow accessをクリックすればOAuth認証が完了する。
一方デスクトップサーバー（http://127.0.0.1:3845/mcp）はFigmaデスクトップアプリをローカルで起動している前提のサーバーで、Figma自身が「特定の組織・エンタープライズ向けのユースケース」向けと位置づけている。しかもこちらは有料プランのDev/Fullシートに限定されており、無料プランや閲覧専用シートでは接続できない。デスクトップサーバーを使う場合は、Figmaデスクトップアプリでデザインファイルを開き、Dev Modeに切り替えたうえで右サイドバーからMCPサーバーを有効化し、次のコマンドで追加する。
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp「なぜかリモートでは動くのにデスクトップでは403になる」「逆にデスクトップの手順書見ながらリモートを設定したら繋がらない」というケースの多くは、この2つを混同したところから始まっている。以降のトラブルシューティングでも、まず自分がどちらを使おうとしているのかを確認してから読んでほしい。
原因1 — 403 Forbidden / 認証エラー
デスクトップサーバーで最も多いのがこれ。Figma公式のヘルプセンターと開発者フォーラムを突き合わせると、原因は大きく3つに分かれる。
1つ目はシートタイプの問題。デスクトップサーバーはDev/Fullシートの有料プランでしか使えないため、無料プランや閲覧専用（Viewer）シートのアカウントで接続しようとすると403で弾かれる。自分のFigmaアカウントがチーム内でどのシートに割り当てられているかは、Figmaの管理画面（Admin > Members）から確認できる。
2つ目はOAuthトークンの失効。一度認証が通っていても、しばらく操作していないとトークンが切れて403に戻ることがある。この場合はClaude Code側で/mcpパネルを開き、該当サーバーを選んで再認証すれば直る。
3つ目はクライアント側の実装が古いケース。MCPのStreamable HTTP仕様では、認証が必要なときにサーバーは401を返してOAuthのディスカバリーフローを開始させるべきとされているが、Figma側が403をプレーンテキストで返す実装になっていた時期があり、JSON-RPC形式を前提にパースするクライアントがそこでエラーになる、という報告がFigmaフォーラムに上がっている。Claude Codeの公式プラグイン経由でインストールしていれば基本的にこの問題には当たらないはずだが、自作のラッパーやプロキシ経由で接続している場合は疑ってみる価値がある。
切り分け方としては、まずclaude mcp get figma（もしくはfigma-desktop）を実行してIssue:行に表示される詳細を確認する。シートの問題かトークンの問題かは、このメッセージである程度絞り込める。
claude mcp get figma-desktop原因2 — Invalid sessionId（-32001）で落ちる
claude mcp listではConnectedと表示されるのに、実際にツールを呼び出すと次のようなエラーで落ちるケースがある。
{"jsonrpc":"2.0","error":{"code":-32001,"message":"Invalid sessionId"},"id":null}これはFigma MCPの初期のドキュメントと実装の間にズレがあった時期に多く報告されていた症状で、/mcpエンドポイントの代わりに/sseエンドポイントを使う、あるいは.mcp.jsonのtypeを"sse"から"http"に変える、といった回避策がコミュニティで共有されていた。
Figma側はこの不整合を修正済みと発表しているが、今もネット上には/sseを使う古い手順を紹介した記事や、typeフィールドを省略した設定例が残っている。これをそのままコピーすると、今度は別の意味で設定が壊れる。Claude Code側にも「urlはあるがtypeがない設定はstdioサーバーとして扱われスキップされる」という仕様があり、typeを書き忘れるとMCP server "<name>" has a "url" but no "type"という別の警告が出る。
対処法は、一度サーバー定義を削除してから、最新の公式手順（type: "http"・エンドポイントは/mcp）で入れ直すことだ。
claude mcp remove figma-desktop
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcpclaude mcp add --transport httpで追加すればtypeは自動的に正しく設定されるので、手動で.mcp.jsonを書いている場合よりも事故が少ない。
原因3 — そもそも繋がらない（Failed to connect / Server not found）
claude mcp listの時点でFailed to connectのまま変わらない場合、デスクトップサーバーを使っているなら疑うべきはFigmaデスクトップアプリ側のローカルブリッジだ。デスクトップサーバーはFigmaアプリ内でポート3845を使ってローカルにサーバーを立てる仕組みになっているため、Figmaアプリ側でセッションが切れていると、Claude Code側からは「接続できるはずなのに繋がらない」ように見える。
Figmaの開発者フォーラムでは、Figmaアプリのヘルプメニューから再起動・リセットを行うことで復旧したという報告が複数上がっている。デスクトップサーバーで接続が不安定なときは、まずFigmaアプリ自体を完全に終了して開き直す、それでも直らなければアプリの設定からトラブルシューティング関連のリセット機能を試す、という順番で切り分けるのが手っ取り早い。
リモートサーバーを使っているのに同じ症状が出る場合は、Figma固有の問題ではなくClaude Code側のMCP接続一般の問題である可能性が高い。その場合はMCP接続全般のトラブルシューティング記事のほうが当てはまることが多い。
原因4 — 削除もできないゾンビ接続（Invalid server ID format）
Figma MCPを一度リモートとデスクトップの両方で試した人によく起きるのがこれ。設定を整理しようとサーバーを削除しようとすると、次のようなエラーが出て削除自体に失敗する。
Invalid server ID format. Expected UUID or mcpsrv_* tagged ID.
Failed to disconnect from server.Anthropicの公式リポジトリのGitHub Issueにも同様の報告があり、原因は.mcp.json（または~/.claude.json）の中にfigma（リモート）とfigma-desktop（デスクトップ）の2つのサーバー定義が同時に存在し、インストール経路が混ざったまま登録されていることだった。
{
"figma": {
"type": "http",
"url": "https://mcp.figma.com/mcp"
},
"figma-desktop": {
"type": "http",
"url": "http://127.0.0.1:3845/mcp"
}
}この状態自体はエラーではないが、片方をプラグイン経由、もう片方をコマンド経由で追加したりすると、内部的な識別子の形式が食い違ってclaude mcp removeが正しいIDを見つけられなくなることがある。報告されている回避策としては、.mcp.jsonと~/.claude.jsonを直接開いて、不要な方のエントリを手動で削除するのが確実だ。CLIコマンドでの削除に失敗する場合は、設定ファイルを直接編集する方法にすぐ切り替えたほうが早い。このIssueは執筆時点で「既報の重複」としてクローズされており、根本的な修正が入ったかどうかは個別に確認したほうがいい。
原因5 — 繋がっているのに極端に遅い
エラーは出ないのに、Figmaのデザインを参照させると応答が異常に遅くなる、というケースもある。これはエラーというより挙動の問題で、大きなデザインファイル（コンポーネントが数百個あるようなデザインシステム全体など）をそのまま参照させると、Claude Codeが裏側で何十回もツール呼び出しを繰り返すことが原因になっていることが多い。
対処法としては、ファイル全体のURLを渡すのではなく、実装したい特定のフレームやコンポーネントのURLを指定してリクエストすることだ。Figmaでは対象の要素を選択した状態で右クリックから「Copy link to selection」を使うと、そのフレーム単位のURLが取得できる。ファイル単位ではなくフレーム単位でお願いするだけで、無駄なツール呼び出しがかなり減る。
原因6 — claude plugin install自体が失敗する
会社のマネージド端末でClaude Codeを使っている場合、claude plugin install figma@claude-plugins-officialのコマンド自体が失敗することがある。Figma公式のセットアップ記事でも「プラグインインストールコマンドが失敗する場合、組織がプラグインインストールをブロックしている可能性がある」と明記されており、この場合はローカルの設定をいじっても直らない。
Claude Codeには管理者向けの設定でdisabledMcpjsonServersのようにMCPサーバーやプラグインの利用を制限する仕組みがあり、企業導入では意図的にブロックされているケースが普通にある。心当たりがある場合は、自分の環境を疑う前に、社内のClaude Code管理者にプラグイン導入のポリシーを確認したほうが早い。
診断の流れをまとめると
ここまでの原因を、実際に手を動かす順番で並べ直すとこうなる。
claude mcp listで自分のサーバーのステータス（Connected・Needs authentication・Failed to connectなど）を確認するclaude mcp get <name>でIssue:の詳細メッセージを読む- リモートかデスクトップか、自分が今どちらを使おうとしているかを再確認する
- デスクトップなら、Figmaアカウントのシートタイプ（Dev/Full必須）を確認する
.mcp.json・~/.claude.jsonを開いて、figma系のエントリが重複していないか目視で確認する- 一度
claude mcp removeしてから、claude mcp add --transport httpで入れ直す - それでも直らなければ、GitHub Issueで同じ症状の報告がないか検索する
大抵はこの1〜6の間で原因が特定できる。7まで行くケースは、こちらでも把握しているだけで複数報告がある既知の不具合である可能性が高い。
FAQ
リモートとデスクトップ、結局どちらを使えばいい？
特別な理由がなければリモートサーバーを使うのが無難。Figma自身が「ほとんどのユーザーが必要とするのはリモート版」と明言しているし、全プラン・全シートで動く分トラブルの原因も少ない。デスクトップサーバーは、社内ネットワークの制約でリモート接続ができない場合や、Figmaデスクトップアプリでの操作と密に連携させたい場合に検討する程度でいい。
Figmaの無料プランでは全く使えない？
リモートサーバー自体は全プラン・全シートで利用できるとFigma公式が明記しているので、無料プランでも接続自体は可能。ただしデスクトップサーバーはDev/Fullシートの有料プラン限定なので、無料プランのアカウントで403が出ている場合はデスクトップサーバーを使おうとしていないか確認する。
VS Code拡張機能のClaude CodeでもDev Mode MCPは同じように使える？
FigmaのMCPサーバーはMCP対応のクライアントであればどれからでも接続できる仕組みなので、VS Code拡張機能のClaude Codeでも設定自体は同じように行える。ただし拡張機能とCLIで内部の接続処理が別実装になっている場合があり、片方だけ調子が悪いという報告も見かける。CLIでは繋がるのに拡張機能だけ繋がらない場合は、拡張機能を再起動・再インストールしてから切り分けるのが早い。
まとめ
Figma MCPが「動かない」ときの原因は、ほとんどが「リモートとデスクトップの混同」「シート要件を満たしていない」「古い手順の/sse設定が残っている」「サーバー定義の重複」のどれかに収束する。エラーメッセージをそのまま検索するより、claude mcp listとclaude mcp getで状況を確認してから、この記事の症状別早見表と照らし合わせたほうが早く原因にたどり着ける。
Figma MCPを含めたおすすめのMCPサーバー構成は別記事にまとめてあるので、これから導入する場合はそちらも参考にしてほしい。
