Claude Media
mcp-builderスキルでClaudeにMCPサーバーを作らせる4フェーズの手順
Claude CodeMCPチュートリアル

mcp-builderスキルでClaudeにMCPサーバーを作らせる4フェーズの手順

Anthropic公開のmcp-builderスキルを使い、Claude CodeにMCPサーバーを設計から評価まで作らせる手順です。導入コマンド、4フェーズ、同梱のevaluation.pyの実行方法を扱います。

読了目安 約14分

mcp-builderは、Anthropicがanthropics/skillsリポジトリで公開しているサンプルスキルの1つです。外部サービスのAPIをClaudeから使えるようにするMCPサーバーを、調査・実装・レビュー・評価の4フェーズで作らせるための手順書(SKILL.md)と、言語別の実装ガイド、評価用スクリプトで構成されています。

このスキルを入れると、「このAPIのMCPサーバーを作って」という依頼に対して、Claudeが設計の判断基準と検証の流れを持った状態で作業を始めます。この記事では、導入からフェーズごとの進め方、同梱の評価スクリプトの動かし方までを順に説明します。

mcp-builderが渡す3種類の中身

スキルのディレクトリには、SKILL.mdのほかにreference/とscripts/があります。

置き場所中身使う場面
SKILL.md中身4フェーズの手順と推奨スタック使う場面作業の最初に読まれる
reference/中身ベストプラクティス、TypeScript版、Python版、評価ガイドの4ファイル使う場面各フェーズで必要になったときに読まれる
scripts/中身evaluation.py、connections.py、example_evaluation.xml、requirements.txt使う場面フェーズ4の評価で動かす

SKILL.mdの説明文は、PythonのFastMCPまたはNode/TypeScriptのMCP SDKでサーバーを作るときに使うもの、と書かれています。つまり対象はこの2系統です。GoやC#など他言語のSDKで書きたい場合は、このスキルの実装ガイドは直接は使えません。設計の考え方だけを借りる形になります。

導入 — example-skillsプラグインから入れる

mcp-builderは、リポジトリのマーケットプレイスが用意するexample-skillsプラグインに含まれています。Claude Codeの中で、次の2コマンドを実行します。

/plugin marketplace add anthropics/skills
/plugin install example-skills@anthropic-agent-skills

example-skillsは、mcp-builder以外にもskill-creator、webapp-testing、frontend-designなど12本を束ねたプラグインです。mcp-builderだけが欲しい場合でも、プラグイン単位でまとめて入ります。

プラグインのコンポーネントにはプラグイン名の名前空間が付きます。そのため名前で直接呼ぶなら/example-skills:mcp-builderの形になります。ただし通常は、MCPサーバーを作りたいという依頼の文面がSKILL.mdのdescriptionに合えば、Claudeがスキルを読み込みます。

webapp-testingなど同じプラグインの他スキルとの関係は、webapp-testingスキルの記事で導入手順を扱っています。スキルの仕組み自体はClaude Code Skills完全ガイドにまとまっています。

依頼の出し方

スキルを入れたら、作りたい対象とスタックを具体的に伝えます。次のような依頼が、フェーズ1に入りやすい形です。

mcp-builderスキルを使って、社内の勤怠APIを操作するMCPサーバーを作って。
言語はTypeScript、ローカル利用なのでstdio。
APIの仕様は docs/attendance-openapi.yaml にある。
まず設計案を出して、承認するまで実装は始めないで。

最後の1行は、このスキルの標準の流れにはない追加です。フェーズ1から2へ進む前に人間の確認が入らないと、ツールの切り方が気に入らなくても実装が済んでしまいます。設計案の承認を挟む指示は、手戻りを減らす実用的な足し方です。

4フェーズの進め方

手順

mcp-builderの作業の流れ

  1. 1

    フェーズ1: 調査と計画

    MCPの設計方針、プロトコル仕様、SDKのドキュメントを読み、実装するエンドポイントを決めます。

  2. 2

    フェーズ2: 実装

    プロジェクトの骨組み、共通処理、各ツールを実装します。入力スキーマはZodまたはPydanticで定義します。

  3. 3

    フェーズ3: レビューとテスト

    コード品質を点検し、ビルドしてMCP Inspectorで動作を確かめます。

  4. 4

    フェーズ4: 評価の作成

    サーバーを使って答える10問の質問を作り、Claudeに解かせて精度を測ります。

フェーズ1: 設計の判断基準を先に読み込む

SKILL.mdはまず設計の考え方を4点挙げます。

  • 包括的なAPIカバレッジと、特定業務向けのワークフローツールのバランスを取る。迷ったら包括的なカバレッジを優先する
  • ツール名に一貫した接頭辞を付ける。例はgithub_create_issue
  • 簡潔な説明と、結果の絞り込みやページ分割で、コンテキストを節約する
  • エラーメッセージで次の手を示す

そのうえで、プロトコル仕様はhttps://modelcontextprotocol.io/sitemap.xmlから探し、各ページを.md付きのURLで取得するよう指示しています。SDKのREADMEも、TypeScript版とPython版のどちらかをWebFetchで読み込む前提です。

推奨スタックは、言語がTypeScript、トランスポートがリモートならステートレスなJSONのStreamable HTTP、ローカルならstdioです。TypeScriptを推す理由として、SDKの品質と、AIモデルが生成しやすい点が挙げられています。

つまりPythonで作りたい場合は、依頼文で言語を指定する必要があります。指定がなければ、推奨に沿ってTypeScriptが選ばれやすくなります。

フェーズ2: 実装で決まる命名と形式

実装の細部はreference/の言語別ガイドに書かれています。ここで決まる主な規約は次のとおりです。

項目TypeScript版Python版
サーバー名TypeScript版{service}-mcp-serverPython版{service}_mcp
ツール登録TypeScript版server.registerTool()Python版@mcp.tool デコレータ
入力検証TypeScript版Zod(.strict()を付ける)Python版Pydantic
ツール名TypeScript版{service}_{action}_{resource}のsnake_casePython版同左

共通のルールとして、ツールはresponse_formatでJSONとMarkdownを切り替えられるようにし、一覧系はlimitを守ってhas_moreやnext_offsetを返す設計が求められます。デフォルトの件数は20〜50件が目安です。

応答が大きくなる場合に備えて、TypeScript版はCHARACTER_LIMITの定数を置いて切り詰め、続きを取る方法をメッセージに含める実装例を載せています。例では25000文字です。

注釈も指定対象です。readOnlyHint、destructiveHint、idempotentHint、openWorldHintの4つをツールごとに設定します。ただし注釈は挙動を伝えるヒントであり、セキュリティ上の保証ではなく、クライアントが注釈だけで安全性を判断してはならない、と明記されています。

フェーズ3: ビルドと検証の最低ライン

TypeScriptではnpm run buildが通ること、MCP Inspectorで確かめることがチェック項目です。MCP Inspectorはnpx @modelcontextprotocol/inspectorで起動します。使い方はMCP Inspectorの使い方に詳しくあります。

Pythonではpython -m py_compileで構文を確かめ、同じくInspectorで試します。

ベストプラクティスにはセキュリティ項目もあります。APIキーは環境変数に置きコードに書かないこと、ファイルパスのディレクトリトラバーサルを防ぐこと、ローカルで動かすStreamable HTTPサーバーは0.0.0.0でなく127.0.0.1にバインドしてOriginヘッダーを検証することなどです。stdioサーバーは標準出力にログを出さず、標準エラーに出すという注意も入っています。

フェーズ4: 10問の評価を作る

mcp-builderの特徴は、実装後に評価を作る工程を標準に組み込んでいる点です。質問は10問で、各問に次の条件が求められます。

  • 他の質問に依存しない
  • 読み取り専用で、状態を変えない
  • 複数のツール呼び出しを要する複雑さがある
  • 答えが文字列比較で検証できる単一の値である
  • 時間が経っても答えが変わらない

最後の条件は見落としやすいところです。評価ガイドは、投稿へのリアクション数、スレッドの返信数、チャンネルのメンバー数のように現在の状態に依存する値を数える問いを避けるよう書いています。

質問と答えは次のXML形式で作ります。

<evaluation>
  <qa_pair>
    <question>2025年度のうち、残業時間が最も長かった月はいつか</question>
    <answer>2025-11</answer>
  </qa_pair>
</evaluation>

上の質問はこの記事用の例で、勤怠の過去データは変わらないので条件を満たします。

評価ガイドは、質問づくりの途中でMCPサーバーの実装コードを読まないよう求めています。ツールの説明とスキーマだけを頼りに、サーバー側の事情に縛られない難しい問いを作るためです。

評価スクリプトの実行

作ったevaluation.xmlは、同梱のscripts/evaluation.pyで実行します。Claudeが実際にツールを呼んで質問に答え、正答率とツールへのフィードバックをレポートにします。

pip install -r scripts/requirements.txt
export ANTHROPIC_API_KEY=your_api_key
 
python scripts/evaluation.py \
  -t stdio \
  -c node \
  -a dist/index.js \
  -e API_TOKEN=xxx \
  -m <使うモデルID> \
  -o eval_report.md \
  evaluation.xml

requirements.txtはanthropicとmcpの2パッケージです。評価はAnthropic APIを呼ぶので、Claude Codeのサブスクリプションとは別に、APIキーと従量課金が必要です。

トランスポートの扱いは2通りに分かれます。

トランスポートサーバーの起動主なオプション
stdioサーバーの起動スクリプトが自動で起動・終了主なオプション-c(コマンド)、-a(引数)、-e(環境変数)
http / sseサーバーの起動事前に自分で起動しておく主なオプション-u(URL)、-H(ヘッダー)

stdioでサーバーを手で起動しておく必要はありません。逆にhttpとsseでは、起動済みのサーバーに接続するだけです。

-mの既定値がclaude-3-7-sonnet-20250219になっている点には注意が必要です。スクリプト側の既定値に頼らず、実行時に使えるモデルIDを-mで明示するほうが確実です。 レポートには、各質問の正誤とエージェントのフィードバックが出ます。精度が低いときの見直しポイントは、ツールの説明が明確か、パラメータの説明が足りているか、返すデータが多すぎないか、エラーメッセージが次の行動を示しているか、の4点です。

設計方針の食い違いに気づいておく

SKILL.mdと実装ガイドを突き合わせると、方針に引っ張り合う箇所が1つあります。

SKILL.mdのフェーズ1は、迷ったら包括的なAPIカバレッジを優先するとしています。一方、TypeScript版の品質チェックリストには「ツールはAPIエンドポイントの薄いラッパーではなく、完結した作業の流れを可能にする」という項目があります。

この2つは、エンドポイントを網羅するか、業務の単位でツールをまとめるかで逆を向きます。依頼で方針を示さないと、どちらの指針に従うかが定まりません。依頼の段階で、どちらに寄せるかを明示するのが現実的です。

  • 汎用クライアントから使われるサーバーなら、エンドポイントを網羅する側
  • 特定業務だけを任せるサーバーなら、業務単位のツールにまとめる側

評価の質問が複数のツール呼び出しを要する作りになっているため、評価の結果を見て、まとめるべきツールを後から見つける使い方もできます。

mcp-server-devプラグインとの違い

Claude Codeのドキュメントは、MCPサーバーの足場づくりに使えるものとして、mcp-server-devプラグインを案内しています。/plugin install mcp-server-dev@claude-plugins-officialで入れ、/mcp-server-dev:build-mcp-serverを実行すると、Claudeが用途を尋ねてリモートHTTPまたはローカルstdioのサーバーを組み立てます。

観点mcp-buildermcp-server-dev
配布元mcp-builderanthropics/skillsのexample-skillsmcp-server-devclaude-plugins-official
起動mcp-builder依頼文のdescription一致、または名前指定mcp-server-dev/mcp-server-dev:build-mcp-server
進め方mcp-builder4フェーズ。評価の作成まで含むmcp-server-dev用途の質問から足場づくり
言語mcp-builderTypeScript(推奨)とPythonmcp-server-devリモートHTTPまたはstdioの選択

どちらかが上位互換というより、足場を素早く得たいときと、設計の判断基準と評価まで通したいときで使い分ける関係です。プラグインごとに名前空間が付くため、コマンド名は重なりません。

作らせる前に確認しておくこと

導入の前後で押さえる点は次のとおりです。

  • Python(FastMCP)かNode/TypeScriptの2系統が対象で、他言語の実装ガイドは含まれていない
  • 評価の実行にはAnthropic APIのキーと従量課金が別に要る
  • -mのモデルIDは実行時に明示する
  • フェーズ1の後に設計案の承認を挟む指示は、自分で足す
  • 外部サービスに書き込むツールは、destructiveHintの設定と、Claude Code側の権限設定の両方で守る

作ったサーバーをClaude Codeに接続するときは、claude mcp addに--transportを付けます。stdioならclaude mcp add --transport stdio <名前> -- <コマンド> [引数...]の形で、--より前がClaude Code側のオプション、後ろがサーバーに渡る部分です。

claude mcp add --transport stdio attendance \
  -e API_TOKEN=xxx \
  -- node /path/to/attendance-mcp-server/dist/index.js

まとめ

mcp-builderは、MCPサーバーの設計判断から実装、検証、10問の評価までを1本の流れにしたスキルです。コード生成よりも、ツールの切り方と評価の作り方に重心があります。包括性か業務単位かの方針と、評価に使うモデルIDは、依頼する側が先に決めておくと手戻りが減ります。接続後の動作確認はMCP Inspectorの手順で行えます。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →