FastMCPを学ぶ - MCPサーバーの例

FastMCPを使って Model Context Protocol (MCP) サーバーを構築する方法を示す学習用プロジェクトです。FastMCP は、MCP互換のツールやリソースを作成するためのPythonフレームワークです。

このプロジェクトについて

このリポジトリには、2つの完全なMCPサーバー実装が含まれています。

• Demo Server - FastMCPの基本を学ぶためのシンプルな例

• Expense Tracker - 本格的な実践向けアプリケーションの例

Claudeや他のAIモデル、カスタムアプリケーションで利用できるMCPサーバーの構築を理解するのに最適です。

Related MCP server: expense-tracker-mcp-server

📋 サーバー1: デモサーバー (main.py)

基本的なツールを備えたシンプルなスターターMCPサーバーです。

ツール

roll_dice(n_dice: int) -> list[int]

n個の6面ダイスを振り、結果を返します。

roll_dice(3) → [4, 2, 6]

add_numbers(a: float, b: float) -> float

2つの数値を加算し、その合計を返します。

add_numbers(5, 3) → 8

デモサーバーの実行

python main.py

💰 サーバー2: 経費トラッカー (test.py)

データベースへの永続化、カテゴリ分類、高度なフィルタリングを備えた総合的な経費管理MCPサーバーです。

特徴

• 永続ストレージ用のSQLiteデータベース

• 階層型カテゴリシステム（メインカテゴリ + サブカテゴリ）

• 日付範囲フィルタリング

• カテゴリ別の経費集計

• CRUD操作（作成・読み取り・更新・削除）

• カテゴリの統合/リネーム

データ構造

各経費エントリには次の項目が含まれます。

• id - 一意の識別子（自動インクリメント）

• date - 経費の日付（文字列形式）

• amount - 数値で表す経費金額

• category - メインカテゴリ（categories.json から取得）

• subcategory - 詳細な追跡用のオプションのサブカテゴリ

• note - オプションの説明・メモ

利用可能なカテゴリ

経費トラッカーは、それぞれに複数のサブカテゴリを持つ12のメインカテゴリをサポートしています。

• Food - 食料品、外食、コーヒーなど

• Transport - 燃料、公共交通機関、タクシー/配車アプリ、駐車場、有料道路

• Housing - 家賃、メンテナンス、固定資産税、修理、家具

• Utilities - 電気、水道、ガス、インターネット、携帯電話、TV

• Health - 医薬品、診察、検査、フィットネス

• Education - 書籍、コース、オンラインサブスクリプション、受験料

• Family & Kids - 学費、保育、おもちゃ、イベント

• Entertainment - 映画、ストリーミングサブスクリプション、ゲーム、お出かけ

• Shopping - 衣類、靴、電化製品、家電、ホームデコレーション、現在はShoppingカテゴリに含まれます

• Subscriptions - SaaSツール、クラウド/AI、音楽、ストレージ、ニュースレター

• Personal Care - サロン、身だしなみ、化粧品、衛生ケア

• Gifts & Donations - プレゼント、チャリティ、フェスティバルギフト

• Finance & Fees - 銀行手数料、投資手数料など

ツール

add_expense(date: str, amount: int, category: str, subcategory: str = "", note: str = "")

新しい経費エントリをデータベースに追加します。

{
  "date": "2026-08-20",
  "amount": 45,
  "category": "food",
  "subcategory": "dining_out",
  "note": "Lunch with friends"
}

戻り値: {"status": "ok", "id": 1}

list_expenses(start_date: str, end_date: str)

指定された日付範囲（両端含む）内のすべての経費を一覧表示します（YYYY-MM-DD形式）。

list_expenses("2026-08-01", "2026-08-31")

すべてのフィールドを含む経費記録の配列を返します。

summarize(start_date: str, end_date: str, category: str = None)

日付範囲内でカテゴリごとの合計金額を取得します。特定のカテゴリで絞り込むこともできます。

summarize("2026-08-01", "2026-08-31")
summarize("2026-08-01", "2026-08-31", "food")

戻り値:

[
  {"category": "food", "total_amount": 150},
  {"category": "transport", "total_amount": 50}
]

update_expense(id: int, date: str = None, amount: float = None, category: str = None, subcategory: str = None, note: str = None)

既存の経費の特定のフィールドを更新します。指定されたフィールドのみが変更されます。

update_expense(1, amount=50, note="Updated note")

戻り値: {"status": "ok", "id": 1, "updated_fields": {...}}

delete_expense(id: int)

IDを指定して経費エントリを削除します。

delete_expense(1)

戻り値: {"status": "ok", "deleted_id": 1}

merge_categories(old_categories: list[str], new_category: str)

1つ以上のカテゴリラベルを新しい1つのカテゴリにリネームまたは統合します。経費カテゴリをまとめるのに役立ちます。

merge_categories(["food", "dining"], "meals")

戻り値: {"status": "ok", "rows_updated": 15, "new_category": "meals"}

リソース

expense://categories

カテゴリ構造をJSONとして返します。このリソースは毎回読み込まれるため、サーバーを再起動せずに categories.json を編集できます。

経費トラッカーの実行

python test.py

データベース: 永続ストレージとして、同じディレクトリに expenses.db を作成します。

インストールとセットアップ

前提条件

• Python 3.14以上

• FastMCP 3.4.7以上

依存関係のインストール

pip install fastmcp>=3.4.7

または、プロジェクトの pyproject.toml を使用する場合：

pip install -e .

プロジェクト構造

learn-fastmcp/
├── main.py              # Demo server (roll_dice, add_numbers)
├── test.py              # Expense Tracker server (full MCP implementation)
├── categories.json      # Category definitions for expense tracker
├── expenses.db          # SQLite database (auto-created by test.py)
├── pyproject.toml       # Project configuration
└── README.md            # This file

学習パス

1. main.py から始める - 基本を学びます：

   • FastMCPインスタンスの作成方法

   • @mcp.tool デコレータを使ってシンプルなツールを定義する方法

   • mcp.run() でサーバーを実行する方法

2. test.py に進む - 高度なパターンを学びます：

   • SQLiteデータベース統合

   • ファイルI/Oとリソース管理

   • 複雑なツールロジック（CRUD操作）

   • @mcp.resource デコレータを使ったリソース

   • オプショナルパラメータと条件付きパラメータ

   • エラーハンドリングとバリデーション

FastMCPの主要概念

ツール

@mcp.tool() でデコレートされた関数は、MCPクライアントから呼び出すことができます。各ツールには以下が含まれます：

• 型ヒント付きの入力パラメータ

• 機能を説明するdocstring

• 戻り値

リソース

URIでアクセスできる静的または動的なコンテンツです。@mcp.resource() で定義します：

• 一意のURIで識別される（例: expense://categories）

• オプションでMIMEタイプを指定可能

• ファイルから読み込むか、動的に計算することができます

サーバーのライフサイクル

mcp = FastMCP("ServerName")  # Create instance

@mcp.tool()                  # Define tools
def my_tool(): ...

if __name__ == "__main__":
    mcp.run()               # Start the server

次のステップ

• デモサーバーを変更して新しいツールを追加する

• 経費トラッカーを新機能で拡張する（例: 予算、振り返る経費）

• 興味のあるドメイン向けに独自のMCPサーバーを作成する

• MCPプロトコルを使ってMCPサーバーをClaudeに接続する

リソース

• MCP Documentation

• FastMCP GitHub

• Python Typing Documentation

楽しく学びましょう！ 🚀