FastMCPチートシート｜MCPサーバー開発・Claude・Cursor・Codex設定

AIエージェントに自作のツールや外部API、ローカルリソースを連携させるオープン標準規格として「Model Context Protocol（MCP）」が普及しています。

その中でも、PythonでMCPサーバーを最も手軽かつ直感的に開発できる高水準フレームワークが「FastMCP」です。Pythonのデコレータを関数に付与するだけで、スキーマ定義や引数バリデーション、プロトコル通信を自動処理してくれるため、開発効率を飛躍的に高めることができます。

この記事は、FastMCPを用いたMCPサーバー開発のPythonコード構文から、Context API、公式CLIコマンド、安全な例外処理、そしてClaude Desktop・Cursor・Codex・Antigravityへの接続設定JSONまでを1ページに集約した実践リファレンスです。「やりたいこと」から最短でコードや設定を引ける早見表形式でまとめていますので、日々の開発やクライアント連携の手元資料としてご活用ください。

この記事でわかること
前提条件・対象読者
1. FastMCP Quick Reference：やりたいこと別早見表
2. FastMCPデコレータと基本構文
3. 型定義と引数バリデーション（Pydantic連携）
4. Context API早見表（ログ出力・進捗報告）
1. Contextの主要メソッド一覧
5. 安全なエラー処理とセキュリティ実装
1. 例外処理：ToolErrorを使った安全なエラー通知
2. セキュリティ：パストラバーサル（ディレクトリ遡り）防止
6. FastMCP公式CLI早見表（run / dev / install / inspect）
1. fastmcp run と python server.py の決定的な違い
7. MCP Inspectorによる対話的デバッグ
1. 方法1：FastMCP公式CLIから起動（推奨）
2. 方法2：スタンドアロンのMCP Inspectorを直接起動
8. 主要AIクライアント設定チートシート（コピペ用JSON）
9. 検索クエリ型FAQ（よくある質問）
まとめ
次に読むおすすめ記事
参考情報

この記事でわかること

目的の構文やコマンドに即座に辿り着ける「FastMCP Quick Reference早見表」
Tool、Resource、Promptの基本定義とデコレータの使い方
Pydanticを活用した型安全な引数バリデーション設計
Context（ログ出力、進捗報告、リソース参照）の活用法
ToolErrorを用いた安全な例外処理とパストラバーサル防止の実装
FastMCP公式CLI（run, dev, install, inspect, list）とMCP Inspectorの使い方
Claude Desktop、Cursor、Codex、Antigravity向けの設定JSONテンプレート（コピペ対応）
検索クエリに応える1問1答FAQ

前提条件・対象読者

対象読者: Pythonの基本構文を理解しており、自作ツールやAPIをAIエージェントに連携させたい開発者
想定OS: Windows 11 / macOS / Linux
対応バージョン: FastMCP 2.x系（最終確認: 2026年9月）
推奨環境: Python 3.10以上、パッケージマネージャー uv
重要注記: 本記事で扱う「FastMCP」は高水準フレームワーク（パッケージ名: fastmcp）です。Anthropic公式の低水準SDK（パッケージ名: mcp）とは別のライブラリであり、開発時のインストールには uv add fastmcp を使用します。
バージョン確認: FastMCPは機能拡張が活発に行われているため、利用時は fastmcp version コマンドでバージョンをご確認ください。

1. FastMCP Quick Reference：やりたいこと別早見表

開発現場で最もよく使う構文、CLIコマンド、クライアント設定への直行インデックスです。

やりたいこと	構文・コマンド・設定	概要
Tool（関数）を公開する	@mcp.tool	AIが実行できる関数を登録
Resource（データ）を公開する	@mcp.resource(“schema://{id}”)	読み取り専用データをAIに提供
Prompt（定型文）を公開する	@mcp.prompt()	再利用可能なプロンプトテンプレート
引数の型と説明を検証する	Field(description=”…”)	PydanticでAIの入力ミスを防止
リアルタイムログを出力する	ctx.info(“message”)	クライアント側へ進行ログを送信
進捗状況を通知する	ctx.report_progress(current, total)	長時間タスクの進捗バーを更新
正しい例外をAIに返す	raise ToolError(“reason”)	スタックトレースを隠しエラーを通知
サーバーを起動する	fastmcp run server.py	stdio通信でサーバーを実行
対話的Inspectorでテストする	fastmcp dev inspector server.py	ブラウザUIでツール動作を確認
サーバーのメタ情報を確認する	fastmcp inspect server.py	登録されたToolやResourceを一覧表示
Claude Desktopに登録する	fastmcp install claude server.py	設定JSONへの追加をCLIから自動化
Claude Desktop設定ファイル	claude_desktop_config.json	手動設定時のJSON定義
Cursor設定ファイル	.cursor/mcp.json	Cursorプロジェクト単位の設定

2. FastMCPデコレータと基本構文

FastMCPの核となる「Tool」「Resource」「Prompt」の基本実装です。

サーバー初期化

from fastmcp import FastMCP

# サーバー名とAI向けの説明文を指定して初期化
mcp = FastMCP(
    name="DevToolsServer",
    instructions="開発作業やデータ集計を支援するカスタムツール群です。"
)

if __name__ == "__main__":
    mcp.run()

ツール定義（@mcp.tool）

関数のdocstringがAIモデルに対するツールの説明文として渡されます。引数の型アノテーションからJSON Schemaが自動生成されます。

@mcp.tool
def calculate_tax(price: int, tax_rate: float = 0.1) -> int:
    """商品の税込金額を計算します。
    
    Args:
        price: 税抜金額（円）
        tax_rate: 消費税率（デフォルト 0.1）
    """
    return int(price * (1 + tax_rate))

リソース定義（@mcp.resource）

AIに読み取り専用のテキストやバイナリデータを提供します。URIスキーマでアクセス先を指定します。

# 静的URIのリソース
@mcp.resource("config://app-settings")
def get_app_settings() -> str:
    """アプリケーションのシステム設定を返します。"""
    return '{"env": "production", "debug": false}'

# 動的パラメータを含むURIリソース
@mcp.resource("users://{user_id}/profile")
def get_user_profile(user_id: str) -> str:
    """指定されたユーザーIDのプロフィール情報を返します。"""
    return f'{{"user_id": "{user_id}", "role": "admin"}}'

プロンプト定義（@mcp.prompt）

AIに特定の役割やタスクを指示するための再利用可能なプロンプトテンプレートを登録します。

@mcp.prompt()
def code_review_prompt(language: str, code: str) -> str:
    """指定された言語のコードレビュー用プロンプトを生成します。"""
    return f"""以下の{language}コードについて、パフォーマンス、セキュリティ、可読性の観点から詳細なコードレビューを実施してください。

対象コード:
{code}"""

3. 型定義と引数バリデーション（Pydantic連携）

AIモデルは型ヒントや説明文（description）を読んで適切な引数を渡します。Pydanticを組み合わせることで、無効な引数を自動で弾き、AIに再試行を促せます。

from pydantic import BaseModel, Field
from typing import Optional, List
from enum import Enum

class OutputFormat(str, Enum):
    JSON = "json"
    TEXT = "text"
    CSV = "csv"

class SearchQuery(BaseModel):
    query: str = Field(..., description="検索キーワード", min_length=2)
    limit: int = Field(10, description="取得件数の上限（1〜50）", ge=1, le=50)
    format: OutputFormat = Field(OutputFormat.JSON, description="出力フォーマット")
    tags: Optional[List[str]] = Field(None, description="絞り込みタグのリスト")

@mcp.tool
def search_database(params: SearchQuery) -> str:
    """指定された検索条件に基づいて社内データベースを照会します。"""
    return f"Query: {params.query}, Limit: {params.limit}, Format: {params.format}"

4. Context API早見表（ログ出力・進捗報告）

ツールの第1引数（または型ヒント）に Context を受け取ることで、クライアント側へのログ通知や進捗バーの表示、リソースの動的読み込みが可能です。

from fastmcp import FastMCP, Context
import time

mcp = FastMCP("ContextDemoServer")

@mcp.tool
async def long_running_task(total_steps: int, ctx: Context) -> str:
    """進捗を報告しながら時間のかかるバッチ処理を実行します。"""
    ctx.info("タスクを開始しました")
    
    for step in range(1, total_steps + 1):
        await ctx.report_progress(progress=step, total=total_steps)
        ctx.debug(f"ステップ {step}/{total_steps} を処理中...")
        time.sleep(0.5)
        
    ctx.info("全ステップが完了しました")
    return "処理が正常に完了しました"

Contextの主要メソッド一覧

メソッド / 属性	用途・シグネチャ	説明
ctx.debug(msg)	ctx.debug(str)	デバッグログをクライアントへ送信
ctx.info(msg)	ctx.info(str)	通常の情報ログをクライアントへ送信
ctx.warning(msg)	ctx.warning(str)	警告メッセージを送信
ctx.error(msg)	ctx.error(str)	エラーメッセージを送信
ctx.report_progress(p, t)	ctx.report_progress(progress, total)	進行状況（数値）を通知してプログレスバーを更新
ctx.read_resource(uri)	await ctx.read_resource(uri)	自身または外部のMCPリソースを動的読み取り
ctx.request_id	属性（文字列）	クライアントからのリクエスト一意識別子

5. 安全なエラー処理とセキュリティ実装

例外処理：ToolErrorを使った安全なエラー通知

ツール内で想定外の例外をそのまま放置するとスタックトレースが流出し、逆に例外を空で握りつぶすとAIが成否を誤認します。FastMCP公式の ToolError を用いて、AIが理解しやすいエラーメッセージを返します。

from fastmcp.exceptions import ToolError

@mcp.tool
def divide_numbers(a: float, b: float) -> float:
    """2つの数値を割り算します。"""
    if b == 0:
        raise ToolError("0で除算することはできません。割る数（b）に0以外の数値を指定してください。")
    return a / b

セキュリティ：パストラバーサル（ディレクトリ遡り）防止

ローカルファイルを読み書きするツールでは、../ による機密ファイル閲覧攻撃を厳密に防御する必要があります。

from pathlib import Path
from fastmcp.exceptions import ToolError

SAFE_DIR = Path("./workspace_data").resolve()

@mcp.tool
def read_workspace_file(file_name: str) -> str:
    """指定された安全なワークスペース内のファイルを読み取ります。"""
    target_path = (SAFE_DIR / file_name).resolve()
    
    # ターゲットパスが安全なベースディレクトリの配下にあるかを厳格判定
    if SAFE_DIR not in target_path.parents and target_path != SAFE_DIR:
        raise ToolError("セキュリティ警告: 許可されたディレクトリ外へのアクセスは禁止されています。")
        
    if not target_path.exists() or not target_path.is_file():
        raise ToolError(f"指定されたファイルが見つかりません: {file_name}")
        
    return target_path.read_text(encoding="utf-8")

6. FastMCP公式CLI早見表（run / dev / install / inspect）

FastMCP 2.xでは強力なコマンドラインインターフェース（CLI）が標準提供されています。

コマンド	使用例	役割
fastmcp run	fastmcp run server.py	サーバーをstdio方式で起動
fastmcp dev	fastmcp dev inspector server.py	開発用MCP Inspectorを起動してテスト
fastmcp install	fastmcp install claude server.py	Claude Desktop等の設定ファイルに自動追加
fastmcp inspect	fastmcp inspect server.py	登録されたToolやResourceの一覧・詳細を表示
fastmcp list	fastmcp list	サーバー内の公開コンポーネントを一覧表示
fastmcp version	fastmcp version	インストール済みFastMCPのバージョン確認

fastmcp run と python server.py の決定的な違い

fastmcp run server.py: ファイル内のFastMCPインスタンスを自動検出して起動します。if __name__ == "__main__": ブロックは実行されません。
python server.py: スクリプトとして直接実行するため、末尾の if __name__ == "__main__": mcp.run() の記述が必須となります。

7. MCP Inspectorによる対話的デバッグ

MCPサーバーのツール呼び出しやリソース取得の挙動をブラウザから対話的にテストできる公式ツールが「MCP Inspector」です。

方法1：FastMCP公式CLIから起動（推奨）

FastMCPが内蔵するコマンドを使用するのが最も手軽です。

fastmcp dev inspector server.py

方法2：スタンドアロンのMCP Inspectorを直接起動

最新のMCP Inspector v2系は npx コマンドから直接呼び出し可能です。

npx @modelcontextprotocol/inspector uv run server.py

ブラウザで表示される管理UIから、各ツールの引数を入力して「Execute」を押すことで、JSON-RPC通信の生ログや戻り値を即座に検証できます。

8. 主要AIクライアント設定チートシート（コピペ用JSON）

各AIエージェント・エディタの設定ファイルパスと、記述するJSONテンプレートです。

1. Claude Desktop の設定

設定ファイル配置場所:
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "my-dev-tools": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "C:\\path\\to\\mcp-server-demo",
        "server.py"
      ]
    }
  }
}

Windows環境の注意点: Claude DesktopにPATHが引き継がれず uv not found エラーが出る場合は、command に C:\\Users\\<ユーザー名>\\.local\\bin\\uv.exe のようにuvの絶対パスを指定してください。また、Windowsのバックスラッシュ（\）は必ず \\ と2重にエスケープします。

2. Cursor の設定

Cursorでは、プロジェクトごとに設定するローカル設定と、全体で共有するグローバル設定が可能です。

プロジェクト固有設定: プロジェクトルート直下の .cursor/mcp.json
ユーザー共通設定: ~/.cursor/mcp.json

{
  "mcpServers": {
    "cursor-tools": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "${workspaceFolder}/scripts/mcp",
        "server.py"
      ]
    }
  }
}

※Cursorの設定画面（Settings > Features > MCP）からもUI経由で同様のコマンド・引数を追加できます。

3. OpenAI Codex / Antigravity の設定

自律型AIエージェントフレームワークにMCPツールを登録する場合の設定形式です。

Codex（設定ファイルまたは環境定義）:

{
  "mcp_servers": {
    "project-tools": {
      "command": "uv",
      "args": ["run", "tools/server.py"],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Antigravity（設定ファイルまたはGEMINI.md）: Antigravity 2.0では、設定ディレクトリ配下のMCP定義、またはワークスペースのルール設定に記載して連携します。

{
  "mcpServers": {
    "local-analyzer": {
      "command": "uv",
      "args": ["run", "server.py"]
    }
  }
}

9. 検索クエリ型FAQ（よくある質問）

Q1: FastMCPと公式のMCP Python SDK（mcp）の違いは何ですか？

mcp（公式SDK）は低レイヤーのプロトコル仕様に忠実な実装ライブラリであり、サーバー構築には多くのボイラープレートコードが必要です。 fastmcp はその上に構築された高水準フレームワークであり、FastAPIのようにデコレータと型アノテーションだけで直感的にサーバーを定義できます。新規のツール開発にはFastMCPが強く推奨されます。

Q2: fastmcp run と python server.py はどう使い分けますか？

fastmcp run server.py はFastMCPのCLI経由で実行し、ホットリロードやInspector連携（fastmcp dev）が利用できます。 Claude DesktopやCursorの設定ファイルから呼び出す際は、仮想環境の整合性を保つため uv run server.py（または python server.py）を指定するのが安定したベストプラクティスです。