MCP Python 開発スキル
mcp SDK (FastMCP を含む) を使用して、Python で MCP サーバーとクライアントを構築します。
クイックオリエンテーション
- パッケージ: PyPI 上の
mcp(FastMCP を含む)。インストール:pip install "mcp[cli]" - LangChain/LangGraph 統合用:
pip install langchain-mcp-adapters - 仕様バージョン:
2024-11-05,2025-03-26,2025-06-18,2025-11-25 - インポート:
from mcp.server.fastmcp import FastMCP, Context, Image
コーディングを始める前に
このスキルの references/ ディレクトリから、ユーザーのニーズに基づいて適切なリファレンスファイルを読んでください:
| ユーザーがしたいこと | 読むべきファイル |
|---|---|
| MCP サーバーの作成 (ツール、リソース、プロンプト) | references/server.md |
| MCP クライアントまたはマルチサーバーエージェントの作成 | references/client.md |
| Context (ロギング、進捗、サンプリング、エリシテーション) の使用 | references/context.md |
| トランスポート、認証、セキュリティ、ライフサイクルの理解 | references/protocol.md |
コードを書く前に、必ず関連するリファレンスファイルを読んでください。 リファレンスには、正確なインポートパス、API シグネチャ、戻り値の型マッピング、および正しいコードに不可欠な落とし穴が含まれています。
アーキテクチャ概要
ホスト (Claude Desktop / IDE / カスタムエージェント)
├── MCP クライアント 1 ──► MCP サーバー A (ローカル、STDIO)
├── MCP クライアント 2 ──► MCP サーバー B (リモート、Streamable HTTP)
└── MCP クライアント 3 ──► MCP サーバー C (リモート、OAuth 2.1)
- ホスト: クライアントを作成する AI アプリケーション
- クライアント: 単一サーバーへの 1:1 接続
- サーバー: ツール、リソース、プロンプトを公開
3つのプリミティブ: ツール (モデル制御の関数)、リソース (アプリ制御の読み取り専用データ)、プロンプト (ユーザー制御のメッセージテンプレート)。
2つのトランスポート: STDIO (ローカルサブプロセス、シングルクライアント) と Streamable HTTP (ネットワーク、マルチクライアント、デフォルトエンドポイント /mcp)。
最小限のサーバーテンプレート (コピペスターター)
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("MyServer")
@mcp.tool()
def my_tool(param: str) -> str:
"""このツールが何をするかを記述します。"""
return f"結果: {param}"
@mcp.resource("data://config")
def get_config() -> str:
"""サーバー設定。"""
return '{"key": "value"}'
if __name__ == "__main__":
mcp.run() # デフォルトは STDIO; HTTP の場合は mcp.run(transport="streamable-http") を使用
最小限のクライアントテンプレート
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client
import asyncio
async def main():
params = StdioServerParameters(command="python", args=["server.py"])
async with stdio_client(params) as (read, write):
async with ClientSession(read, write) as session:
await session.initialize()
result = await session.call_tool("my_tool", {"param": "hello"})
print(result.content[0].text)
asyncio.run(main())
主要なルールと落とし穴
@mcp.tool()関数には docstring が必須 — これが LLM に送信されるツール説明になります。docstring がないと、LLM はツールの機能を認識できません。- 型ヒントは必須 — FastMCP はこれらから JSON スキーマを生成します。
Annotated[str, Field(description="...")]を使用してリッチなパラメータドキュメントを提供します。 - Context は型ヒントによって注入される — パラメータとして
ctx: Contextを追加すると、ツールの入力スキーマから自動的に除外されます。 - 戻り値の型に注意:
str→ TextContent、dict→ JSON TextContent、bytes→ BlobResourceContents、Image→ ImageContent、list→ 複数のコンテンツブロック。 - エラー: ツール内で例外を発生させる →
isError=Trueで LLM に返されます。エラー文字列を通常の出力として返さないでください。 - STDIO サーバーは決して stdout に出力してはいけません — すべての非 MCP 出力は stderr に送られます。stderr ハンドラ付きの
loggingまたはctx.info()を使用してください。 - I/O を行うツールでは非同期が推奨されます。同期ハンドラと非同期ハンドラの両方がサポートされています。
- ツールアノテーションはヒントであり、強制ではない:
readOnlyHint、destructiveHint、idempotentHint、openWorldHint。 - MultiServerMCPClient (v0.1.0+) は非同期コンテキストマネージャーではありません。直接インスタンス化します:
client = MultiServerMCPClient({...})。 - InMemorySaver は開発専用 — 本番環境では PostgresSaver または SqliteSaver を使用してください。
開発ワークフロー
mcp dev server.py # MCP Inspector (デバッグ UI) で起動
mcp dev server.py --with pandas # 追加の依存関係と共に
mcp install server.py # Claude Desktop に登録
mcp install server.py -e API_KEY=x # 環境変数と共に
mcp run server.py # 直接実行
各トランスポートの使用タイミング
| シナリオ | トランスポート | 理由 |
|---|---|---|
| ローカル CLI ツール / デスクトップ統合 | STDIO | ネットワーク不要、マイクロ秒レイテンシ |
| 本番 API、マルチクライアント | Streamable HTTP | スケーラブル、負荷分散可能 |
| サーバーレス (Lambda、Cloud Run) | Streamable HTTP + stateless_http=True | リクエストごとにステートレス |
| 既存の FastAPI/Starlette への埋め込み | Streamable HTTP (マウント) | ASGI アプリを共有 |