【2026年9月】Claude Code×Figma MCP接続の実装手順

Q: 403 Forbiddenが出ました。どう切り分けますか？

自分で Authorization ヘッダーを設定していないなら、Claude Codeは401でも403でも「サインインが必要」と判定して /mcp に印を付けるので、そこから認証をやり直します。ヘッダーを自分で設定している場合は印が付かず接続失敗として報告されるため、直す対象はそのトークンです。まず「ヘッダーを自分で書いたか」を確認してください。

Q: チーム全員に同じ設定を配るにはどうしますか？

プロジェクトスコープで追加して、生成される .mcp.json をバージョン管理に入れます。ただし、クローンしたリポジトリではワークスペースの信頼ダイアログを通すまで承認が適用されず、サーバーは「Pending approval」で止まります。セットアップ手順書に「初回は claude を起動して信頼ダイアログに答える」を明記してください。

FigmaのデザインをClaude Codeで実装するにはFigma MCPの接続が要ります。リモート版とデスクトップ版の選び分け、登録2ルート、403で止まったときの読み方、チームへの配り方を公式情報で整理しました。

2026年9月10日時点の結論。FigmaのデザインをClaude Codeで実装に落とすときの入口は、公式プラグインでリモート版のFigma MCPサーバーを入れ、/mcp でサインインする、この2手で足りる。Figmaのヘルプセンターが案内している手順もこの形で、リモート版は全シート・全プランで使える。デスクトップ版は「Figmaで選択したものをそのまま渡したい」ときの追加線であり、最初から両方入れる必要はない。

Figma MCPの記事が読まれる理由は、たいてい「入れたのに繋がらない」か「自分の環境では動いたがチームの誰かで動かない」のどちらかだ。この2つは接続の話ではなく、認証と設定スコープの話で決まる。ここを先に押さえると、デザインから実装への受け渡しは日常の作業に落ちる。

この記事の要点

既定ルート：claude plugin install figma@claude-plugins-official を実行し、/plugin から figma を選んで認証する。Figma公式のClaude Code向けヘルプがこの手順を案内している。
手動ルート：claude mcp add --transport http figma https://mcp.figma.com/mcp でも同じサーバーに繋がる。
提供条件：リモート版は全シート・全プラン。デスクトップ版は有料プランのDevシートまたはFullシートで、接続先は http://127.0.0.1:3845/mcp。
403の読み方：Claude Codeはリモートサーバーが 401 または 403 を返したとき「サインインが必要」と判定して /mcp に印を付ける。ただし自分で Authorization ヘッダーを設定していた場合は接続失敗として扱われる（Connect Claude Code to tools via MCP）。
配り方：チームで共有するならプロジェクトスコープ（.mcp.json）、自分だけならユーザースコープ。同じ名前を複数スコープに置くと警告が出る。
対象読者：フロントエンド担当、デザインエンジニア、デザインシステムの運用担当、開発リード。
今日やること：claude mcp list を実行し、いまFigma系のサーバーが何個・どのスコープに入っているかを数える。

手順1｜リモート版とデスクトップ版のどちらを繋ぐか決める

Figma MCPサーバーには、Figmaが運用するリモート版と、Figmaデスクトップアプリの中で動くデスクトップ版の2種類がある。名前が似ているので同じものだと思われがちだが、使える条件も、デザインの渡し方も違う。

Figma MCPサーバーをリモート版とデスクトップ版に振り分け、提供条件とデザインの渡し方の違いを示した図 — 提供条件とデザインの渡し方で選び分ける

比べる点	リモート版	デスクトップ版
提供条件	全シート・全プランで利用可	有料プランのDevシートまたはFullシート
接続先	`https://mcp.figma.com/mcp`	`http://127.0.0.1:3845/mcp`
Figmaデスクトップアプリ	不要	必要（Dev Modeで有効化する）
デザインの渡し方	フレームやレイヤーのリンクを渡す	Figma側で選択したものを渡せる
使えるツールの範囲	読み取りに加えて書き込み系も含む	読み取り中心

Figmaのヘルプセンターは、リモート版を「ほとんどのユーザーに必要なもので、機能の幅がもっとも広い」と位置づけている。デスクトップ版の出番は、Figmaのキャンバスで選んだフレームをそのまま渡したいときだ。Figma公式のツール一覧にも「選択範囲による指示はデスクトップ版でのみ動作し、リモート版はフレームまたはレイヤーのリンクを必要とする」と明記されている（Tools and prompts）。

判断はシンプルでよい。まずリモート版だけを入れる。デザイナーと画面共有しながら「いま選んでいるこれ」を渡す場面が業務に含まれるなら、あとからデスクトップ版を別名で足す。両方入れる場合も、サーバー名は figma と figma-desktop のように分けておく。同じ名前で2つ定義すると、後述する警告の対象になる。

なお、接続できるクライアントは限定されている。FigmaはMCPカタログに載っているクライアントだけがFigma MCPサーバーに接続できるとしており、Claude Codeはその対象に入っている。

手順2｜Claude Codeに登録する（プラグイン経由と手動の2ルート）

登録には公式プラグインを使うルートと、claude mcp add を直接叩くルートがある。Figma公式のClaude Code向け手順は前者だ。

プラグイン経由（Figma公式が案内するルート）

claude plugin install figma@claude-plugins-official

claude-plugins-official はAnthropicが管理する公式マーケットプレイスで、Claude Codeを対話モードで初めて起動したときに自動登録される。非対話で先に起動した場合や、マーケットプレイスのポリシーで以前の登録が止められていた場合は、claude plugin marketplace add anthropics/claude-plugins-official で自分で登録する（Extend Claude Code with plugins）。

インストール後の流れは次のとおり。

Claude Codeが起動中なら再起動する。
/plugin を実行してプラグインマネージャーを開く。
「Installed」タブに移動し、figma を選ぶ。
認証画面が外部ブラウザで開くので「Allow access」を押す。
ターミナルに戻り、もう一度 /plugin を開いて figma が「connected」になっているか確認する。

インストールコマンド自体が失敗する場合、Figmaのヘルプはその原因を「組織がプラグインのインストールを止めている（全プラグイン、またはFigmaプラグインだけ）可能性が高い」と説明している。企業アカウントでこれに当たったら、次の手動ルートに切り替えるより先に、管理設定側を確認したほうが早い。

手動ルート（`claude mcp add`）

# リモート版
claude mcp add --transport http figma https://mcp.figma.com/mcp

# デスクトップ版（Figma側でDev ModeのMCPサーバーを有効にしてから）
claude mcp add --transport http figma-desktop http://127.0.0.1:3845/mcp

HTTPはリモートMCPサーバーに繋ぐときの推奨トランスポートで、クラウドサービスでもっとも広くサポートされている形式だ。.mcp.json や ~/.claude.json に直接書く場合は type を必ず入れる。url があって type がないエントリは設定エラーとして扱われ、Claude Codeはそのサーバーを読み込まずに「url があるのに type がない」という趣旨のメッセージを出す。MCPの仕様書がこのトランスポートを streamable-http と呼んでいるため、type には streamable-http も別名として通る。

claude plugin installから再起動・/plugin・Allow accessを経てconnectedを確認するまでの流れと、claude mcp addという別ルートを示した図 — 登録から接続確認までの流れ

デスクトップ版を使う場合の前段は、Claude Code側ではなくFigma側の操作になる。Figmaデスクトップアプリでデザインファイルを開き、ツールバーのトグルでDev Modeに切り替え、右サイドバーでMCPサーバーを有効にして、表示されたサーバーアドレスを控える。控えたアドレスを上のコマンドに入れる。

手順3｜/mcp で認証する（403で止まったときの読み方）

追加しただけでは繋がらない。リモート版はOAuthでのサインインが要る。

/mcp

/mcp を開いて figma を選び、ブラウザ側でアクセスを許可する。ブラウザが自動で開かないときは、表示されたURLを手でコピーして開く。認証後にリダイレクトが接続エラーになった場合は、ブラウザのアドレスバーにあるコールバックURL全体を、Claude Code側に出るURL入力欄に貼り付ける。

ここで多い詰まりが「403」だ。Claude Codeの挙動は公式ドキュメントに整理されていて、読み方は次のように分かれる。

まだサインインしていないサーバー：401 Unauthorized でも 403 Forbidden でも、サインインが必要な状態として /mcp に印が付く。ここでOAuthを完了すれば解決する。
自分で Authorization ヘッダーを設定したサーバー：接続時の 401 や 403 では印が付かない。直すべきなのは自分が設定した資格情報なので、Claude Codeは「接続失敗」として報告する。トークンがそのMCPエンドポイント向けに有効かを確認するか、ヘッダーを外してOAuthに任せる。
サインイン済みで、あとから 401 が返った場合：Claude Codeが保存済みトークンを更新して再接続し、リクエストを1回だけ再試行する。それでも失敗したときにだけ /mcp に印が付く。

つまり、Figma MCPで403が出たときの最初の分岐は「自分でヘッダーを書いたかどうか」だ。書いていないなら認証をやり直す。書いているなら、そのトークンを疑う。

403 Forbiddenが出たときにAuthorizationヘッダーの有無でサインインが必要と接続失敗に分かれ、それぞれの対処を示した図 — 403が出たときの分岐

コマンドラインだけで済ませたいときは、claude mcp login figma でOAuthフローをシェルから直接動かせる。SSH越しやディスプレイのないLinuxでは、ブラウザを開かずに認証URLを表示する挙動になるので、手元のブラウザで開いてリダイレクトURLを貼り戻す。この貼り付けには対話端末が要るため、ssh -t で接続しておく。資格情報を消すときは claude mcp logout figma を使う。

状態の確認は claude mcp list と claude mcp get figma で行う。接続に失敗しているサーバーは、claude mcp get の Issue: 行にHTTPステータスやエラーコードと、サーバーが返したエラー文言が出る。この詳細表示にはClaude Code v2.1.219以降が要る。

手順4｜チーム全員に同じ設定を配る（スコープの選び方）

「自分の環境では動く」を終わらせるのはスコープの設計だ。MCPサーバーは3つのスコープで設定でき、どこに置くかで読み込まれる範囲と共有可否が変わる。

ユーザー・プロジェクト・ローカルの3スコープと保存先、共有可否、承認待ちで止まる状態を示した図 — 3つのスコープと保存先

スコープ	読み込まれる範囲	チームと共有	保存先
ローカル（既定）	いま作業中のプロジェクトだけ	しない	`~/.claude.json`
プロジェクト	いま作業中のプロジェクトだけ	する（バージョン管理経由）	プロジェクト直下の `.mcp.json`
ユーザー	自分の全プロジェクト	しない	`~/.claude.json`

Figma MCPの置き場所は、リポジトリの性格で決める。デザインが紐づく特定のフロントエンドリポジトリで全員が使うなら、プロジェクトスコープにして .mcp.json をコミットする。

claude mcp add --transport http figma --scope project https://mcp.figma.com/mcp

複数のリポジトリを行き来する個人環境なら、ユーザースコープのほうが手間が少ない。

claude mcp add --transport http --scope user figma https://mcp.figma.com/mcp

.mcp.json を配るときに知っておくべき挙動が2つある。

1つ目はワークスペースの信頼だ。v2.1.196以降、claude mcp list と claude mcp get は、リポジトリにコミットされていない設定ファイルからの承認を、そのフォルダで claude を実行して信頼ダイアログを受け入れるまで読み込まない。クローンしてきたリポジトリが自分自身のサーバーを承認することはできず、.claude/settings.json にコミットされた enableAllProjectMcpServers や enabledMcpjsonServers は信頼されていないフォルダでは無視される。この状態のサーバーは接続されず「Pending approval」のまま止まる。新メンバーが「設定は入っているのに繋がらない」と言うときは、まずここを見る。

2つ目は名前の重複だ。同じサーバー名を複数のスコープで、別のエンドポイントで定義すると、claude mcp list と /mcp で警告が出る。OAuthのサインインはエンドポイント単位で保存されるので、片方で認証してももう片方では改めてサインインが要る。要らないほうは claude mcp remove figma --scope local のように、スコープを指定して消す。

MCPサーバーを組織全体へ配る設計そのものは、Claude Code管理MCP配布の手順とMCP認証を安全にチーム配布する方法で扱っている。Figmaだけでなく複数のサーバーを配る段階になったら、そちらの設計に寄せたほうが破綻しない。

手順5｜デザインの渡し方と、返ってくる情報の量を決める

接続できたら、次は「何を渡すか」だ。Figma MCPサーバーの読み取り系ツールは、公式のツール一覧に名前と役割が並んでいる。実装でよく使うのは次のあたりになる。

get_design_context：レイヤーまたは選択範囲からデザインの文脈を取り出す。既定の出力はReact + Tailwindで、プロンプトで変えられる。
get_metadata：選択範囲の構造を、基本的なプロパティを持つ簡素なXMLの形で返す。
get_screenshot：選択範囲のスクリーンショットを取る。
get_variable_defs：選択範囲で使われている変数とスタイルを返す。
get_code_connect_map：ノードIDとコードコンポーネントの対応を返す。

渡し方は手順1で選んだサーバーによって変わる。デスクトップ版なら「Figmaで選択しているもの」をそのまま指せる。リモート版はフレームまたはレイヤーのリンクが要るので、Figma側でリンクをコピーしてプロンプトに貼る運用になる。チームで手順書を書くなら、この一手をスクリーンショット付きで固定しておくと質問が減る。

もう1つ、実装現場で効いてくるのが出力量の上限だ。Claude CodeはMCPツールの出力が10,000トークンを超えると警告を出し、既定では25,000トークンで打ち切る。上限は MAX_MCP_OUTPUT_TOKENS 環境変数で引き上げられるが、警告のしきい値は固定されている。

export MAX_MCP_OUTPUT_TOKENS=50000

大きなフレームを丸ごと渡すと、この上限に当たって情報が欠けたまま実装が始まる。画面1枚を一度に渡すより、セクション単位・コンポーネント単位に切って渡すほうが結果が安定する。画像を返すツールはこの上限の対象から外れないので、get_screenshot を多用する運用では特に効いてくる。

タイムアウト側の調整も覚えておくとよい。サーバーごとのツール実行時間は .mcp.json のそのサーバーのエントリに timeout（ミリ秒）を足して上書きでき、起動時のタイムアウトは MCP_TIMEOUT 環境変数で変えられる。

手順6｜出力を自社の書き方に寄せる

Figma MCPの既定出力はReact + Tailwindだ。自社のコードベースがそれと違うなら、返ってきたものをそのまま貼るのではなく、出力の形を先に指定する。効かせ方は3層ある。

1層目はプロンプト。公式ドキュメントも既定の出力はプロンプトでカスタマイズできると書いている。「このリポジトリの components/ui にある既存コンポーネントを使い、新しいCSSクラスを増やさない」のように、使ってよい部品と増やしてはいけないものを同時に指定する。

2層目は変数とスタイル。get_variable_defs で色や余白の定義を取り出し、ハードコードされた値ではなくデザイントークン側の名前で書かせる。デザインシステムを持っているチームでは、ここを飛ばすと「見た目は合っているがトークンを使っていないコード」が量産される。

3層目はコードとの対応付け。get_code_connect_map はFigmaのノードIDと実際のコードコンポーネントの対応を返す。対応が張られていれば、生成側が既存コンポーネントを呼ぶ形に寄る。

そして、この3つを毎回プロンプトで書き直さないために、リポジトリの CLAUDE.md に実装規約として置く。「UIはこのディレクトリの部品から組む」「色は変数名で指定する」「新規のCSSファイルを作らない」といった規約は、会話ごとに言い直すものではない。フロント実装側の詰まりどころはReact/Next.jsでの実装ガイドに、デザイナー側から見た使い方はWeb/UIデザインの実装事例にまとめてある。

手順7｜想定シナリオ：デザイン改修の受け渡しを型にする

ここから先は実在の顧客事例ではなく、上の手順を1つのチームに当てはめた想定シナリオとして読んでほしい。所要時間や削減率のような測定値は置かない。決めごとの順番だけを示す。

前提（想定）：フロントエンド3人とデザイナー2人のプロダクトチーム。Figmaは有料プラン、リポジトリはNext.js、デザインシステムのコンポーネントは実装済み。

サーバーの線引き：リモート版をプロジェクトスコープで .mcp.json に置き、コミットする。デザイナーと同席するレビュー会用に、希望者だけデスクトップ版を figma-desktop の名前でユーザースコープに足す。
初回セットアップの手順書：新メンバーがやることを3行にする。リポジトリで claude を起動して信頼ダイアログに答える、/mcp で figma にサインインする、claude mcp list で connected を確認する。
渡す単位のルール：画面全体ではなくコンポーネントかセクション単位で渡す。渡すときは対象のFigmaリンクと、使ってよい既存コンポーネント名を一緒に書く。
規約の置き場所：使ってよい部品、トークン名の指定、新規CSSの禁止を CLAUDE.md に書く。プロンプトの中に散らさない。
レビューの固定：生成された差分は必ず人がレビューする。何をどこまでエージェントに任せるかの線引きは権限設計ガイドの考え方をそのまま持ち込む。

この形にすると、デザイン改修が来たときの会話が「どう繋ぐか」から「どの単位で渡すか」に移る。繋ぎ方の話が毎回出てくるチームは、まだ手順4のスコープ設計が終わっていない。

つまずきやすい失敗と対処

❌ claude mcp add しただけで使い始める
⭕ 追加は登録であって認証ではない。/mcp でサインインを済ませ、claude mcp list で connected を確認してから作業に入る。非対話実行（claude -p）では /mcp のパネルが出ないため、その場でOAuthを完了できない。先に対話セッションか claude mcp login で済ませておく。

❌ 403を見た瞬間にトークンを再発行する
⭕ 自分で Authorization ヘッダーを設定していないなら、403はOAuthのやり直しで解決する種類の状態として /mcp に出る。逆にヘッダーを自分で設定している場合は、Claude Codeは接続失敗として扱うので、そのトークンがMCPエンドポイント向けに有効かを見る。順番を逆にすると、無関係な鍵を作り直すことになる。

❌ 画面1枚をまとめて渡す
⭕ MCPツールの出力は既定で25,000トークンまでで、10,000トークンを超えると警告が出る。渡す単位を小さくするか、MAX_MCP_OUTPUT_TOKENS を引き上げる。切り詰められた出力で実装を始めると、欠けた部分が後から手戻りになる。

❌ 個人の ~/.claude.json にだけ設定を置いてチームに配ったつもりになる
⭕ 共有はプロジェクトスコープの .mcp.json で行う。加えて、クローン直後のフォルダでは信頼ダイアログを通すまで承認が効かず、サーバーは「Pending approval」で止まる。セットアップ手順書にこの一手を入れる。

❌ 同じ figma という名前でスコープを重ねる
⭕ 同名・別エンドポイントの定義は警告の対象で、サインインもエンドポイントごとに別管理になる。claude mcp remove <name> --scope <scope> で片方を消し、リモート版とデスクトップ版は名前を分ける。

まとめ｜今日からの3手

接続・認証・渡し方の規約という3段の階段と、それぞれを確認するclaude mcp list・/mcp・CLAUDE.mdを示した図 — 接続 → 認証 → 渡し方の規約の順に組む

claude mcp list で、いまFigma系のサーバーが何個・どのスコープにあるかを数える。重複していれば片方を消す。
リモート版を入れて /mcp でサインインし、connected を確認する。プラグイン経由が通らない環境なら claude mcp add --transport http の手動ルートに切り替える。
渡す単位（コンポーネントかセクション）と、使ってよい既存部品を CLAUDE.md に1節書く。

3つとも設定と文章だけで終わる。順番は「接続 → 認証 → 渡し方の規約」で、逆にすると規約を書く対象が決まらない。MCP全体の設定や自作サーバーまで踏み込むならMCP実践ガイドを、プラグインという配布形式そのものを整理したい場合はプラグイン完全ガイドを続けて読んでほしい。

よくある質問

Figma MCPは無料プランでも使えますか？

リモート版のFigma MCPサーバーは全シート・全プランで利用できるとFigmaのヘルプセンターに記載があります。一方、Figmaデスクトップアプリの中で動くデスクトップ版は、有料プランのDevシートまたはFullシートが条件です。まずリモート版から試すのが確実です。

`claude plugin install` が失敗します。原因は何ですか？

Figmaのヘルプは、インストールコマンドが失敗する原因として「組織がプラグインのインストールを止めている（全プラグイン、またはFigmaプラグインだけ）可能性が高い」を挙げています。組織アカウントで使っている場合は、手動ルートに切り替える前に管理側の設定を確認してください。手動なら claude mcp add --transport http figma https://mcp.figma.com/mcp で同じリモートサーバーに繋がります。

403 Forbiddenが出ました。どう切り分けますか？

自分で Authorization ヘッダーを設定していないなら、Claude Codeは401でも403でも「サインインが必要」と判定して /mcp に印を付けるので、そこから認証をやり直します。ヘッダーを自分で設定している場合は印が付かず接続失敗として報告されるため、直す対象はそのトークンです。まず「ヘッダーを自分で書いたか」を確認してください。

チーム全員に同じ設定を配るにはどうしますか？

プロジェクトスコープで追加して、生成される .mcp.json をバージョン管理に入れます。ただし、クローンしたリポジトリではワークスペースの信頼ダイアログを通すまで承認が適用されず、サーバーは「Pending approval」で止まります。セットアップ手順書に「初回は claude を起動して信頼ダイアログに答える」を明記してください。

大きなデザインを渡すと出力が途中で切れます。

Claude CodeはMCPツールの出力が10,000トークンを超えると警告を出し、既定では25,000トークンで打ち切ります。MAX_MCP_OUTPUT_TOKENS 環境変数で上限を引き上げられますが、警告のしきい値は固定です。実務では、上限を上げるより渡す単位を小さくするほうが結果が安定します。

出力がReactとTailwindになります。他の書き方にできますか？

Figma公式のツールドキュメントは、既定の出力がReact + Tailwindであり、プロンプトでカスタマイズできると説明しています。使ってよい既存コンポーネント、トークン名での指定、新規CSSの禁止といった規約は、毎回のプロンプトではなくリポジトリの CLAUDE.md に置くと安定します。

参考・出典

Figma「Guide to the Figma MCP server」（リモート版は全シート・全プラン、デスクトップ版は有料プランのDev／Fullシート、リモートの接続先 https://mcp.figma.com/mcp）
Figma「Claude Code and Figma: Set up the MCP server」（claude plugin install figma@claude-plugins-official、/plugin からの認証手順、デスクトップ版の http://127.0.0.1:3845/mcp、インストール失敗時の組織ポリシー）
Figma「Tools and prompts」（get_design_context・get_metadata・get_screenshot・get_variable_defs・get_code_connect_map の役割、既定出力はReact + Tailwind、選択範囲はデスクトップ版のみ）
Figma「Figma MCP server」（リモート版が推奨で機能の幅が広いこと、接続できるクライアントはMCPカタログ掲載のものに限られること）
Anthropic「Connect Claude Code to tools via MCP」（claude mcp add --transport http の書式、スコープ3種と保存先、.mcp.json の type 必須と streamable-http 別名、401／403の扱い、claude mcp login／logout、ワークスペース信頼と「Pending approval」、同名スコープ重複の警告、出力の警告10,000トークン・上限25,000トークンと MAX_MCP_OUTPUT_TOKENS、timeout と MCP_TIMEOUT）
Anthropic「Extend Claude Code with plugins」（claude-plugins-official の位置づけと自動登録、claude plugin marketplace add anthropics/claude-plugins-official）