Claude CodeにReact Spectrum MCPを入れてS2部品で書かせる手順

React Spectrum MCPサーバーは、Claude Codeに「React Spectrum(S2)の公式ドキュメントを読む手段」を渡すものです。部品を生成するサーバーではありません。登録はclaude mcp addの1コマンドで済み、あとは頼み方と規約で出来が決まります。

React Spectrum S2は、Adobeが公開するReactのUIコンポーネントライブラリです。見た目の調整はstyleマクロとSpectrumのトークンで行い、部品側が持たないプロパティは受け付けません。この独特の流儀を、Claudeが記憶で書くとつまずきやすい箇所です。ここではS2を使うプロジェクトを前提に、登録、ツール、権限、頼み方、Agent Skillsとの使い分けの順で進めます。

前提環境

必要なものは次のとおりです。

• Claude Code(CLI)が使える状態であること
• Node.jsが入っていること。MCPサーバーをnpxで起動するため、公式ページもNode.jsの導入を前提条件に挙げています
• 実装先のプロジェクトで@react-spectrum/s2を使っている、または使う予定であること

npm install @react-spectrum/s2

S2はスタイルの記述にstyleマクロを使います。マクロはビルド時に実行される仕組みなので、バンドラー側の設定が要ります。Viteならunplugin-parcel-macrosを入れてvite.config.tsにmacros.vite()を足し、Next.jsならnext.config.tsにmacros.webpack()を足します。Next.js 16以降では、unplugin-parcel-macrosがTurbopackでは動かないため、アプリを--webpackフラグ付きで起動する必要があります。

MCPサーバーはこの設定を代行しません。ドキュメントを返すだけです。バンドラーの設定が済んでいないプロジェクトでは、Claudeにコードを書かせる前に、導入ページの手順を先に終えておきます。

Claude Codeに登録する

公式のAIページには、Claude Code(CLI)向けに次のコマンドが載っています。

claude mcp add react-spectrum-s2 npx @react-spectrum/mcp@latest

npxで起動するstdio型のサーバーで、@latestを付けているので起動のたびに最新版が使われます。npmのパッケージ情報では、Node 18以上が指定されています。

このコマンドの書き込み先は、既定ではローカルスコープです。登録したプロジェクトでだけ有効で、設定は自分専用になります。チームで同じ構成を使うなら、--scope projectを付けて.mcp.jsonに書き出し、リポジトリにコミットします。次は.mcp.jsonに書いた場合の一例です。

{
  "mcpServers": {
    "react-spectrum-s2": {
      "command": "npx",
      "args": ["@react-spectrum/mcp@latest"]
    }
  }
}

JSONのまま登録したいなら、claude mcp add-jsonの手順が使えます。

登録後は、Claude Codeの中で/mcpを実行して一覧に出ているか見ます。シェルからならclaude mcp get react-spectrum-s2でも状態を確認できます。プロジェクトスコープで入れた場合は、claudeを対話モードで一度起動して承認する手順が挟まります。承認前はPending approvalと表示され、接続されません。

Claude Desktop向けの導線

公式ページの「Claude Code (Desktop)」タブには、Claude Desktopに追加するためのリンクが置かれています。ClaudeのコネクタディレクトリにもReact Spectrum (S2)が載っており、提供元はAdobe、掲載は2026年4月、表示は「Anthropic verified」です。CLIで使うなら、上のコマンドで足ります。

MCPサーバーが提供する9つのツール

READMEのツール表には9つが載っています。前半の6つがS2用、後半の3つがReact Aria用です。コネクタのページに並ぶのは前半の6つです。

後半のlist_react_aria_pages、get_react_aria_page_info、get_react_aria_pageは、同じ構成でReact Ariaのドキュメントを引くツールです。同じサーバーに同梱されているので、S2のサーバーを入れれば別途登録しなくても使えます。React Ariaだけを単独で登録したい場合の手順は、React Aria MCPをClaude Codeに登録する記事にあります。

ツール表に載っている説明は、どれもページの一覧・取得、名前の検索、値の取得です。ファイルを書いたり編集したりするツールは載っていません。実装を書くのはClaude Code本体で、サーバーは仕様の取り寄せ口にあたります。

節単位で引く理由

ページ全文を毎回取り込むと、コンテキストを食います。Claude Codeは、MCPツールの出力が10,000トークンを超えると警告を出し、既定では25,000トークンまでに切り詰めます。上限はMAX_MCP_OUTPUT_TOKENS環境変数で変えられますが、警告の閾値は固定です。

節単位の取得なら、上限を上げる設定をしなくても収まりやすくなります。依頼文にページ名と節名を添えると、Claudeがget_s2_page_infoで見出しを見てからget_s2_pageにsection_nameを渡す流れになります。

権限ルールでまとめて許可する

初期設定のままだと、MCPツールの呼び出しごとに許可を求められます。ツール表の範囲では取得と検索だけなので、サーバー単位でまとめて許可する構成が考えられます。.claude/settings.jsonには次のように書けます。

{
  "permissions": {
    "allow": ["mcp__react-spectrum-s2__*"]
  }
}

ツールの名前はmcp__<サーバー名>__<ツール名>の形で、ここでのサーバー名はclaude mcp addで付けたreact-spectrum-s2です。別の名前で登録したなら、ルールもその名前に合わせます。許可ルールのワイルドカードは、mcp__react-spectrum-s2__*のようにサーバー名まで書いたあとにだけ使えます。mcp__*のような広い書き方は許可としては効かず、警告つきで無視されます。

S2の流儀を踏み外させない頼み方

MCPを登録しても、ドキュメントを引くかどうかはClaudeの判断に委ねられます。頼む文に「先にMCPでドキュメントを読んでから」と添えれば、引く前提で動かせます。

後者は、読む場所、スタイルの付け方、実装後の検証を指定しています。

stylesプロパティの制約は規約に書く

S2の部品が受け付けるstylesプロパティは、レイアウト、余白、サイズ、位置に関する限られたCSSプロパティだけです。スタイルのページには、margin、marginStart、width、flexGrow、position、zIndexなどが一覧で載っています。色や内側のパディングは、Spectrumの部品の中では変えられません。

公式の例は、次の形です。

import {style} from '@react-spectrum/s2/style' with {type: 'macro'};
import {Button} from '@react-spectrum/s2/Button';
 
<Button styles={style({marginStart: 8})}>Edit</Button>

stylesにbackgroundColorのような一覧外のプロパティを渡すと受け付けられません。ここはS2で手戻りが出やすい箇所なので、規約として固定しておきます。

CLAUDE.mdに書く規約

毎回の依頼文を短くしたいなら、CLAUDE.mdに規約を書いておきます。次は書き方の一例です。

## UI部品のルール
- UI部品は @react-spectrum/s2 を使う。自前でARIA属性を組まない。
- 実装前に react-spectrum-s2 MCP の get_s2_page で該当ページの節を読む。記憶で書かない。
- アイコン名は search_s2_icons で引いて確かめる。推測で名前を書かない。
- style マクロの値は get_style_macro_property_values で確かめる。
- Spectrum部品の styles プロパティには、レイアウト・余白・サイズ・位置だけを渡す。
- 実装後に型チェックとビルドを実行し、結果を報告する。

最後の行が要点です。MCPが渡すのはドキュメントだけなので、書いたコードが通るかは別に確かめます。検証コマンドの実行を規約に入れておけば、出力を読んで直す反復が回ります。アイコンの行も同じ考え方で、名前が存在するかを検索ツールで確かめさせ、存在しないインポートによるビルド失敗を減らす狙いです。

Agent Skillsと一緒に使う

公式ページには、MCPとは別にAgent Skillも案内されています。インストールは次のコマンドです。

npx skills add https://react-spectrum.adobe.com

Agent Skillsは、AIコーディングツールが関連する作業のときに読み込む、指示・スクリプト・リソースのフォルダです。ドキュメントがスキルの形で配られていて、ローカルに入れて使えます。Claude Code側のスキルの仕組みはClaude Code Skillsのfrontmatterとあわせて確認できます。

MCPとスキルは別の仕組みなので、両方を入れても競合しません。役割は次のように分けられます。

S2のドキュメントは、各ページのURLに.mdを付けるとMarkdownで取得できます。llms.txtには対象ページの一覧もあります。MCPを入れずに、Claudeへ「https://react-spectrum.adobe.com/styling.mdを読んで」と頼むやり方も成立します。

shadcn/uiのように部品そのものをプロジェクトへ追加するサーバーとは、役割が違います。そちらはshadcn MCPを使ったUI部品の追加にあります。S2のサーバーは、仕様を読ませる側です。

動かないときの切り分け

起動に時間がかかって接続が失敗するなら、MCP_TIMEOUTで起動待ちの上限を伸ばせます。ミリ秒指定で、MCP_TIMEOUT=10000 claudeは10秒です。