Communityコーディング＆開発github.com

MCPサーバー開発ガイド

LLMが外部サービスと連携できる高品質なMCP（Model Context Protocol）サーバーを作成するためのガイドです。Python（FastMCP）またはNode/TypeScript（MCP SDK）を使用して、外部APIやサービスを統合するMCPサーバーを構築する際に利用します。

MCPサーバー開発ガイド とは？

このスキルは、LLM（大規模言語モデル）が外部サービスと対話できるようにするMCP（Model Context Protocol）サーバーを開発するための包括的なガイドです。開発プロセスを4つのフェーズ（調査・計画、実装、テスト、評価）に分け、各フェーズで具体的なステップとベストプラクティスを提供します。TypeScript（推奨）とPythonの両方に対応しており、SDKバージョン（v1/v2）ごとのドキュメントやコード例へのリンクも含まれています。ツールの命名規則、入力/出力スキーマの設計、エラーハンドリング、ページネーション対応、評価問題の作成方法など、実践的なノウハウを網羅。特に、APIカバレッジの優先、ワークフローツールとのバランス、エラーが発生した際のアクション可能なメッセージ設計など、エージェントが効率的にタスクを遂行できるための設計思想が強調されています。

対応✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/anthropics/skills/tree/main/skills/mcp-builder

Installed? Explore more コーディング＆開発 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

オリジナルを見る→すべてのスキルを見る

お気に入りのAIに質問する

このエージェントスキルを事前に読み込んだ状態で新しいチャットを開きます。

OpenAIChatGPTClaudeClaudeGeminiGeminiGrokGrokPerplexityPerplexityDeepSeekDeepSeek

ドキュメント

MCPサーバー開発ガイド は何をしますか？

概要

LLMが外部サービスと対話できるようにするための、MCP（Model Context Protocol）サーバーを作成します。MCPサーバーの品質は、LLMが実際のタスクをどれだけうまく実行できるかによって測られます。

プロセス

🚀 高レベルワークフロー

高品質なMCPサーバーの作成には、4つの主要なフェーズがあります。

フェーズ1：徹底的な調査と計画

1.1 現代のMCPデザインを理解する

APIカバレッジ vs ワークフローツール： 包括的なAPIエンドポイントカバレッジと、専門化されたワークフローツールのバランスを取ります。ワークフローツールは特定のタスクに便利ですが、包括的なカバレッジはエージェントに操作を自由に組み合わせる柔軟性を与えます。パフォーマンスはクライアントによって異なります。基本的なツールを組み合わせるコード実行が有効なクライアントもいれば、より高レベルのワークフローが適しているクライアントもいます。不確かな場合は、包括的なAPIカバレッジを優先してください。

ツールの命名と発見可能性： 明確で説明的なツール名は、エージェントが適切なツールを素早く見つけるのに役立ちます。一貫性のあるプレフィックス（例：github_create_issue、github_list_repos）とアクション指向の命名を使用してください。

コンテキスト管理： エージェントは、簡潔なツールの説明と、結果をフィルタリング/ページネーションする機能の恩恵を受けます。焦点を絞った関連データを返すツールを設計してください。一部のクライアントはコード実行をサポートしており、エージェントがデータを効率的にフィルタリングおよび処理するのに役立ちます。

アクション可能なエラーメッセージ： エラーメッセージは、具体的な提案と次のステップを示すことで、エージェントを解決策へと導く必要があります。

1.2 MCPプロトコルドキュメントを調べる

MCP仕様をナビゲートする：

サイトマップから関連ページを見つけます：https://modelcontextprotocol.io/sitemap.xml

その後、マークダウン形式で特定のページを.mdサフィックスを付けて取得します（例：https://modelcontextprotocol.io/specification/draft.md）。

確認すべき主要ページ：

  • 仕様の概要とアーキテクチャ
  • トランスポートメカニズム（ストリーミング可能HTTP、stdio）
  • ツール、リソース、プロンプトの定義

1.3 フレームワークドキュメントを調べる

推奨スタック：

  • 言語：TypeScript（高品質なSDKサポートと多くの実行環境での優れた互換性、例えばMCPB。さらに、AIモデルはTypeScriptコードの生成が得意であり、その広範な使用、静的型付け、優れたリンティングツールの恩恵を受けます）
  • トランスポート：リモートサーバーにはストリーミング可能HTTP（ステートフルなセッションやストリーミング応答とは対照的に、ステートレスJSONを使用するため、スケーリングと保守が容易）。ローカルサーバーにはstdio。

フレームワークドキュメントを読み込む：

TypeScriptの場合（推奨）：

TypeScript SDKには2つの主要バージョンがあります。コードを書き始める前にどちらかを選択してください：

  • v2（@modelcontextprotocol/server）：現在の安定版リリース。新しいサーバーにはこちらを使用してください。
  • v1（@modelcontextprotocol/sdk）：バグおよびセキュリティ修正のみを受け付けます。プロジェクトのpackage.jsonがすでに@modelcontextprotocol/sdkに依存している場合、またはnpx @modelcontextprotocol/codemod@latest v1-to-v2 .でそのプロジェクトを移行する場合にのみ使用してください。

プロジェクトがすでにv1を使用している場合は、ユーザーに一度だけ、v2（@modelcontextprotocol/server）が現在の安定版リリースであること、v1はバグとセキュリティ修正のみを受け付けること、npx @modelcontextprotocol/codemod@latest v1-to-v2 .でプロジェクトを移行できることを、1～2文で伝えてください。その後、ユーザーが移行を希望しない限り、v1で続行してください。

1つのプロジェクトで2つのバージョンを混在させないでください。v1のコードサンプル（@modelcontextprotocol/sdk/...からのインポート）はv2には適用されません。

  • TypeScript SDK（v2）：WebFetchを使用してhttps://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdを読み込んでください。完全なドキュメントインデックスはhttps://ts.sdk.modelcontextprotocol.io/v2/llms.txtです。
  • ⚡ TypeScriptガイド（v2） - TypeScriptのパターンと例
  • v1プロジェクトのみ：https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.mdおよびTypeScriptガイド（v1）

Pythonの場合：

  • Python SDK：WebFetchを使用してhttps://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdを読み込んでください。
  • 🐍 Pythonガイド - Pythonのパターンと例

1.4 実装を計画する

APIを理解する： サービスのAPIドキュメントを確認し、主要なエンドポイント、認証要件、データモデルを特定します。必要に応じてWeb検索とWebFetchを使用してください。

ツールの選択： 包括的なAPIカバレッジを優先します。実装するエンドポイントをリストアップし、最も一般的な操作から始めてください。

フェーズ2：実装

2.1 プロジェクト構造を設定する

プロジェクト設定については、言語固有のガイドを参照してください：

2.2 コアインフラストラクチャを実装する

共有ユーティリティを作成する：

  • 認証機能付きAPIクライアント
  • エラーハンドリングヘルパー
  • レスポンスフォーマット（JSON/Markdown）
  • ページネーションサポート

2.3 ツールを実装する

各ツールについて：

入力スキーマ：

  • TypeScriptではZod、PythonではPydanticを使用
  • 制約と明確な説明を含める
  • フィールドの説明に例を追加

出力スキーマ：

  • 構造化データには可能な限りoutputSchemaを定義
  • ツールレスポンスでstructuredContentを使用（TypeScript SDKの機能）
  • クライアントがツール出力を理解し処理するのに役立つ

ツールの説明：

  • 機能の簡潔な要約
  • パラメータの説明
  • 戻り値の型スキーマ

実装：

  • I/O操作にはasync/awaitを使用
  • 適切なエラーハンドリングとアクション可能なメッセージ
  • 該当する場合はページネーションをサポート
  • 最新のSDKを使用する場合は、テキストコンテンツと構造化データの両方を返す

アノテーション：

  • readOnlyHint：true/false
  • destructiveHint：true/false
  • idempotentHint：true/false
  • openWorldHint：true/false

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

3.1 コード品質

以下を確認する：

  • 重複コードがないこと（DRY原則）
  • 一貫性のあるエラーハンドリング
  • 完全な型カバレッジ
  • 明確なツールの説明

3.2 ビルドとテスト

TypeScript：

  • npm run buildを実行してコンパイルを確認
  • v2プロジェクト：ビルドされたサーバーに対して、v2ガイドのセルフチェックスクリプトを実行
  • MCPインスペクターでテスト：npx @modelcontextprotocol/inspector

Python：

  • 構文確認：python -m py_compile your_server.py
  • MCPインスペクターでテスト

詳細なテスト方法と品質チェックリストについては、言語固有のガイドを参照してください。

フェーズ4：評価を作成する

MCPサーバーを実装した後、その有効性をテストするための包括的な評価を作成します。

完全な評価ガイドラインについては✅ 評価ガイドを読み込んでください。

4.1 評価の目的を理解する

評価を使用して、LLMがMCPサーバーを効果的に使用して現実的で複雑な質問に答えられるかどうかをテストします。

4.2 10個の評価質問を作成する

効果的な評価を作成するには、評価ガイドで概説されているプロセスに従います：

  1. ツールの検査：利用可能なツールをリストアップし、その機能を理解する
  2. コンテンツの探索：読み取り専用操作を使用して利用可能なデータを探索する
  3. 質問の生成：10個の複雑で現実的な質問を作成する
  4. 回答の検証：自分で各質問を解いて回答を検証する

4.3 評価要件

各質問が以下を満たしていることを確認する：

  • 独立している：他の質問に依存しない
  • 読み取り専用：破壊的な操作を必要としない
  • 複雑：複数のツール呼び出しと深い探索を必要とする
  • 現実的：人間が気にする実際のユースケースに基づいている
  • 検証可能：文字列比較で検証できる単一の明確な回答がある
  • 安定している：時間が経っても回答が変わらない

4.4 出力形式

この構造でXMLファイルを作成する：

<evaluation>
  <qa_pair>
    <question>AIモデルのローンチについて、動物のコードネームを使用した議論を見つけてください。あるモデルはASL-Xという形式の特定の安全性指定を必要としていました。斑点のあるワイルドキャットにちなんで名付けられたモデルについて決定されていたXの数字はいくつですか？</question>
    <answer>3</answer>
  </qa_pair>
<!-- その他のqa_pair... -->
</evaluation>

参考ファイル

📚 ドキュメントライブラリ

開発中に必要に応じてこれらのリソースを読み込んでください：

コアMCPドキュメント（最初に読み込み）

  • MCPプロトコル：サイトマップhttps://modelcontextprotocol.io/sitemap.xmlから始め、.mdサフィックスを付けて特定のページを取得
  • 📋 MCPベストプラクティス - 普遍的なMCPガイドライン。以下を含む：
    • サーバーとツールの命名規則
    • レスポンス形式ガイドライン（JSON vs Markdown）
    • ページネーションのベストプラクティス
    • トランスポートの選択（ストリーミング可能HTTP vs stdio）
    • セキュリティとエラーハンドリングの標準

SDKドキュメント（フェーズ1/2で読み込み）

  • Python SDK：https://raw.githubusercontent.com/modelcontextprotocol/python-sdk/main/README.mdから取得
  • TypeScript SDK（v2）：https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/main/README.mdから取得；完全なドキュメントインデックスはhttps://ts.sdk.modelcontextprotocol.io/v2/llms.txt
  • TypeScript SDK（v1、既存のv1プロジェクトのみ）：https://raw.githubusercontent.com/modelcontextprotocol/typescript-sdk/v1.x/README.mdから取得

言語固有の実装ガイド（フェーズ2で読み込み）

  • 🐍 Python実装ガイド - 完全なPython/FastMCPガイド。以下を含む：

    • サーバー初期化パターン
    • Pydanticモデルの例
    • @mcp.toolを使用したツール登録
    • 完全な動作例
    • 品質チェックリスト

  • ⚡ TypeScript実装ガイド（SDK v2） - @modelcontextprotocol/serverのための完全なTypeScriptガイド。以下を含む：

    • プロジェクト設定とサーバーファクトリ
    • ツールデザイン：Zod 4スキーマ、出力形式、ページネーション、エラー
    • stdioとストリーミング可能HTTP、ベアラー認証を提供する完全な例
    • リソース、プロンプト、通知
    • ビルドされたサーバーを検証するセルフチェックスクリプト
    • 高度な機能のためのSDK例へのリンク
    • v1→v2変換テーブル、移行手順、品質チェックリスト

  • ⚡ TypeScript実装ガイド（SDK v1） - 既存の@modelcontextprotocol/sdkプロジェクトのための同等のガイド

評価ガイド（フェーズ4で読み込み）

  • ✅ 評価ガイド - 完全な評価作成ガイド。以下を含む：
    • 質問作成ガイドライン
    • 回答検証戦略
    • XML形式仕様
    • 質問と回答の例
    • 提供されたスクリプトを使用した評価の実行

Individual skills in this repo

This repo contains 19 individual skills — each has its own dedicated page.

academy-guide

Stop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content.

algorithmic-art

Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists

anthropics/template-skill

Replace with description of the skill and when Claude should use it.

brand-guidelines

Applies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.

canvas-design

Create beautiful visual art in .png and .pdf documents using design philosophy. You should use this skill when the user asks to create a poster, piece of art, design, or other static piece. Create original visual designs, never copying existing artists

claude-api

|-

discernment-nudge

After you give a substantive answer or draft that the user may act on — advice or recommendations, drafted artifacts such as goals, plans, pitches, proposals, or emails, estimates or projections, analysis or interpretation of data, factual claims they may rely on, or a multi-step argument — invoke this skill BEFORE finalizing your reply and then, if it applies, append 2-3 short follow-up questions, each tied to something specific in what you just produced, that help the user check key facts, probe the reasoning or assumptions, and notice missing context. Do this at most once per conversation. Skip it when the user asked a trivial how-to or simple lookup, wants a purely educational explanation, asked you only to format, convert, or assemble a file from content they provided, is writing code they will run, is doing creative writing or casual chat, or already asked you to double-check, cite, or review — the skill file explains these boundaries and the exact output format.

doc-coauthoring

Guide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks.

docx

Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files) or Word templates (.dotx files). Triggers include: any mention of

frontend-design

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

internal-comms

A set of resources to help me write all kinds of internal communications, using the formats that my company likes to use. Claude should use this skill whenever asked to write some sort of internal communications (status reports, leadership updates, 3P updates, company newsletters, FAQs, incident reports, project updates, etc.).

pdf

Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.

pptx

Use this skill any time a .pptx or .potx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx or .potx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates (.potx), layouts, speaker notes, or comments. Trigger whenever the user mentions \

skill-creator

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill

slack-gif-creator

Knowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like

theme-factory

Toolkit for styling artifacts with a theme. These artifacts can be slides, docs, reportings, HTML landing pages, etc. There are 10 pre-set themes with colors/fonts that you can apply to any artifact that has been creating, or can generate a new theme on-the-fly.

webapp-testing

Toolkit for interacting with and testing local web applications using Playwright. Supports verifying frontend functionality, debugging UI behavior, capturing browser screenshots, and viewing browser logs.

web-artifacts-builder

Suite of tools for creating elaborate, multi-component claude.ai HTML artifacts using modern frontend web technologies (React, Tailwind CSS, shadcn/ui). Use for complex artifacts requiring state management, routing, or shadcn/ui components - not for simple single-file HTML/JSX artifacts.

xlsx

Use this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like \

関連スキル

steipete/bluebubbles

Send and manage iMessages via BlueBubbles, including attachments, tapbacks, edits, replies, and groups.

community

steipete/eightctl

Control Eight Sleep pods (status, temperature, alarms, schedules).

community

steipete/blucli

BluOS CLI (blu) for discovery, playback, grouping, and volume.

community

steipete/bear-notes

Create, search, and manage Bear notes via grizzly CLI.

community

steipete/camsnap

Capture frames or clips from RTSP/ONVIF cameras.

community

steipete/gifgrep

Search GIF providers with CLI/TUI, download results, and extract stills/sheets.

community
← More コーディング＆開発 skills