Fastmcp

Python で MCP サーバーを作り、試し、公開します。

skill の情報

参考: SKILL.md 全文

FastMCP

FastMCP を使って Python で MCP サーバーを作り、手元で動作を確かめ、MCP クライアントに登録し、HTTP のエンドポイントとして公開します。

いつ使うか

次のような作業のときに、この skill を使います。

• Python で新しい MCP サーバーを作る
• API・データベース・CLI・ファイル処理の流れを MCP のツールとして包む
• ツールに加えて、リソースやプロンプトも見せる
• Hermes などのクライアントにつなぐ前に、FastMCP の CLI でサーバーをひととおり試す
• Claude Code、Claude Desktop、Cursor といった MCP クライアントにサーバーを登録する
• FastMCP のサーバーのリポジトリを、HTTP で公開できる形に整える

サーバーがすでにあって、あとは Hermes につなぐだけなら native-mcp を使います。作るのではなく、既存の MCP サーバーを CLI から手早く叩きたいだけなら mcporter を使います。

事前に必要なもの

まず、作業する環境に FastMCP を入れます。

pip install fastmcp
fastmcp version

API 用のテンプレートを使うなら、httpx が入っていない場合は入れておきます。

pip install httpx

同梱されているファイル

テンプレート

• templates/api_wrapper.py - 認証ヘッダーに対応した REST API のラッパー
• templates/database_server.py - 読み取り専用の SQLite クエリサーバー
• templates/file_processor.py - テキストファイルの中身を調べて検索するサーバー

スクリプト

• scripts/scaffold_fastmcp.py - テンプレートを写して、サーバー名の差し込み箇所を置き換えます

参考資料

• references/fastmcp-cli.md - FastMCP の CLI の使い方、登録先、公開前の確認事項

進め方

1. いちばん小さく成立する形を選ぶ

まずは、役に立つ範囲でいちばん狭い形から始めます。

• API のラッパー: API 全体ではなく、価値の高いエンドポイント 1〜3 個から始めます
• データベースのサーバー: 読み取り専用の構造確認と、範囲を絞ったクエリだけを見せます
• ファイル処理: パスを明示的に受け取り、結果が毎回同じになる操作だけを見せます
• プロンプト・リソース: 使い回せるプロンプトの雛形や、探せる文書がクライアント側で必要になったときだけ足します

ツールの名前がぼんやりした大きなサーバーより、名前と docstring とスキーマがはっきりした薄いサーバーのほうが扱いやすくなります。

2. テンプレートから雛形を作る

テンプレートをそのまま写すか、雛形作りの補助スクリプトを使います。

python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py \
  --template api_wrapper \
  --name "Acme API" \
  --output ./acme_server.py

使えるテンプレートの一覧はこうして見ます。

python ~/.hermes/skills/mcp/fastmcp/scripts/scaffold_fastmcp.py --list

手で写す場合は、__SERVER_NAME__ を実際のサーバー名に置き換えてください。

3. まずツールから作る

リソースやプロンプトを足す前に、@mcp.tool の関数から始めます。

ツールを設計するときの決まりごとです。

• どのツールにも、動詞をもとにした具体的な名前を付けます
• docstring は、利用者が読むツールの説明として書きます
• 引数は明示的に、型を付けて書きます
• できるかぎり JSON にできる構造化されたデータを返します
• 危なそうな入力は早めに弾きます
• 最初の版では、読み取りだけの動きにしておきます

よいツール名の例です。

• get_customer
• search_tickets
• describe_table
• summarize_text_file

よくないツール名の例です。

• run
• process
• do_thing

4. リソースとプロンプトは、役に立つときだけ足す

スキーマ、方針の文書、生成したレポートのように、読み取り専用の安定した内容をクライアントが取りに来ると便利な場合に @mcp.resource を足します。

決まった作業の流れに向けて、使い回せるプロンプトの雛形をサーバー側から渡したいときに @mcp.prompt を足します。

文書を片っ端からプロンプトにしないでください。次の使い分けをおすすめします。

• 動かすものはツール
• データや文書を取ってくるものはリソース
• 使い回す LLM への指示はプロンプト

5. どこかにつなぐ前に、サーバーを試す

手元で確かめるには FastMCP の CLI を使います。

fastmcp inspect acme_server.py:mcp
fastmcp list acme_server.py --json
fastmcp call acme_server.py search_resources query=router limit=5 --json

手を入れながら素早く直したいときは、サーバーを手元で動かします。

fastmcp run acme_server.py:mcp

HTTP でのやりとりを手元で試すにはこうします。

fastmcp run acme_server.py:mcp --transport http --host 127.0.0.1 --port 8000
fastmcp list http://127.0.0.1:8000/mcp --json
fastmcp call http://127.0.0.1:8000/mcp search_resources query=router --json

サーバーが動くと言い切る前に、新しいツールそれぞれに対して fastmcp call を最低 1 回は実際に流してください。

6. 手元で問題がなければクライアントに登録する

FastMCP は、対応している MCP クライアントにサーバーを登録できます。

fastmcp install claude-code acme_server.py
fastmcp install claude-desktop acme_server.py
fastmcp install cursor acme_server.py -e .

その端末にすでに設定されている MCP サーバーを確かめるには fastmcp discover を使います。

Hermes につなぐことが目的なら、次のどちらかにします。

• native-mcp の skill を使って ~/.hermes/config.yaml にサーバーを設定する
• 仕様が固まるまでは、開発中は FastMCP の CLI コマンドを使い続ける

7. 手元での仕様が固まってから公開する

ホスティングを任せたいなら、FastMCP の資料でいちばん詳しく説明されているのは Prefect Horizon です。公開する前に、こうして確認します。

fastmcp inspect acme_server.py:mcp

リポジトリに次のものが入っているか確かめてください。

• FastMCP のサーバーオブジェクトが入った Python のファイル
• requirements.txt か pyproject.toml
• 公開に必要な環境変数の説明

一般的な HTTP ホスティングを使うなら、まず手元で HTTP でのやりとりを確かめてから、サーバーのポートを外に出せる Python 対応のプラットフォームに載せます。

よくある型

API ラッパー型

REST や HTTP の API を MCP のツールとして見せるときに使います。

最初に用意するとよい範囲です。

• 読み取りの経路をひとつ
• 一覧・検索の経路をひとつ
• 必要なら死活確認

作るときの注意です。

• 認証情報は直接書かず、環境変数に置きます
• リクエストの処理はひとつの補助関数にまとめます
• API のエラーは、短く状況を添えて返します
• 上流の返り値がばらついているときは、揃えてから返します

templates/api_wrapper.py から始めてください。

データベース型

安全な範囲でクエリと構造確認をできるようにするときに使います。

最初に用意するとよい範囲です。

• list_tables
• describe_table
• 範囲を絞った読み取りクエリをひとつ

作るときの注意です。

• データベースへのアクセスは既定で読み取り専用にします
• 最初の版では SELECT 以外の SQL を弾きます
• 返す行数に上限を設けます
• 行と一緒に列名も返します

templates/database_server.py から始めてください。

ファイル処理型

必要に応じてファイルを調べたり変換したりするサーバーのときに使います。

最初に用意するとよい範囲です。

• ファイルの中身を要約する
• ファイルの中を検索する
• 毎回同じ結果になるメタデータを取り出す

作るときの注意です。

• ファイルのパスは明示的に受け取ります
• ファイルが無い場合と、文字コードで失敗した場合を確かめます
• プレビューと結果の件数に上限を設けます
• どうしても外部のツールが要る場合を除いて、シェルの呼び出しは避けます

templates/file_processor.py から始めてください。

満たすべき水準

FastMCP のサーバーを引き渡す前に、次のすべてを確かめてください。

• サーバーが問題なく import できる
• fastmcp inspect <file.py:mcp> が成功する
• fastmcp list <server spec> --json が成功する
• 新しいツールそれぞれについて、fastmcp call を実際に 1 回は流してある
• 環境変数が説明されている
• ツールの数が、推測しなくても把握できる程度に収まっている

困ったとき

FastMCP のコマンドが見つからない

いま使っている環境にパッケージを入れます。

pip install fastmcp
fastmcp version

fastmcp inspect が失敗する

次を確かめてください。

• ファイルを import したときに落ちるような処理が入っていないか
• <file.py:object> で指定した FastMCP のインスタンス名が合っているか
• テンプレートが使っている追加のパッケージが入っているか

Python では動くのに CLI から動かない

こうして確かめます。

fastmcp list server.py --json
fastmcp call server.py your_tool_name --json

たいていはこれで、名前の食い違い、必須の引数の抜け、シリアライズできない返り値が見つかります。

Hermes から公開したサーバーが見えない

サーバー側は正しくても、Hermes の設定のほうが合っていないことがあります。native-mcp の skill を読み込み、~/.hermes/config.yaml にサーバーを設定してから Hermes を再起動してください。

参考資料

CLI の詳細、登録先、公開前の確認事項は references/fastmcp-cli.md を読んでください。