FrontCreation Logo

TECH BLOG

Claude CodeでFigma MCPサーバーが接続できない時の解決法

claude-code
figma
mcp

2025.08.29

Claude CodeでFigma MCPサーバーを使おうとした際、「デスクトップのClaudeで設定したのに、Claude Code上で読み取りに失敗する」という問題に遭遇しました。

この記事では、この問題の原因と解決手順について詳しく解説します。

問題の概要

デスクトップ版のClaudeアプリケーションではFigma MCPサーバーが正常に動作しているのに、Claude Code（CLI版）では以下のような状況になってしまいます：

  • Figma関連のMCPツールが利用できない
  • /mcpコマンドでMCPサーバーが表示されない
  • Figmaデザインの読み取りができない

原因の特定

この問題の根本原因は、MCP設定のスコープの違いにありました。

デスクトップ版Claudeで設定したMCPサーバーは「ユーザーレベル」の設定として保存されます。一方、Claude Codeでは以下の3つのスコープでMCPサーバーを管理します：

  1. プロジェクトスコープ - .mcp.jsonファイル（プロジェクト固有）
  2. ローカルスコープ - ローカル設定ファイル
  3. ユーザースコープ - ユーザー全体の設定

Claude Codeは、プロジェクトスコープの設定を最優先で読み込むため、プロジェクトに.mcp.jsonが存在しない場合、他のスコープの設定も参照されない場合があります。

解決手順

ステップ1：プロジェクトルートに.mcp.jsonを作成

プロジェクトのルートディレクトリに.mcp.jsonファイルを作成します：

{
  "mcpServers": {
    "figma-developer-mcp": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--stdio"],
      "env": {}
    }
  }
}

ステップ2：Figma MCPサーバーの動作確認

設定が正しく行われているか確認します：

npx -y figma-developer-mcp --version

正常に動作している場合は、バージョン番号（例：0.5.2）が表示されます。

ステップ3：Claude Codeの再起動

重要： MCP設定ファイルを追加しただけでは、新しいMCPツールは利用できません。Claude Codeを一度終了し、再起動する必要があります。

# 現在のClaude Codeセッションを終了
/exit
# または Ctrl+C
 
# Claude Codeを再起動
claude

ステップ4：接続確認

再起動後、以下のコマンドでMCPサーバーの接続状況を確認できます：

/mcp

正常に接続されている場合、以下のツールが利用可能になります：

  • mcp__get_figma_data - Figmaファイルのデザインデータを取得
  • mcp__download_figma_images - Figma内の画像をダウンロード

設定のベストプラクティス

プロジェクト固有のMCP設定

プロジェクトで特定のMCPツールを使用する場合は、.mcp.jsonをプロジェクトルートに配置することを推奨します。これにより：

  • チーム全体で同じMCP環境を共有できる
  • プロジェクト固有の設定を管理できる
  • バージョン管理システムで設定を追跡できる

.gitignoreの考慮事項

.mcp.jsonファイルをバージョン管理に含めるかどうかは、プロジェクトの性質によって決定してください：

# MCP設定をバージョン管理から除外する場合
.mcp.json
 
# または、サンプル設定のみを管理する場合
.mcp.json
!.mcp.json.example

トラブルシューティング

MCPサーバーが起動しない場合

以下の点を確認してください：

  1. Node.js環境の確認

    node --version
npm --version

  2. npxの動作確認

    npx --version

  3. ネットワーク接続の確認

    • npmレジストリへの接続が可能か確認

権限エラーが発生する場合

MCPサーバーの実行に必要な権限が不足している可能性があります：

# npmの権限設定を確認
npm config list

まとめ

Claude CodeでFigma MCPサーバーを使用する際は、プロジェクトレベルでの設定が必要です。デスクトップ版Claudeの設定とは独立しているため、プロジェクトごとに.mcp.jsonファイルを作成し、適切にMCPサーバーを設定しましょう。

設定後は必ずClaude Codeの再起動を行うことで、新しいMCPツールが利用可能になります。この手順により、Figmaデザインの読み取りや画像のダウンロードなど、強力なデザイン連携機能を活用できるようになります。

一覧へ戻る