Pythonの「FastMCP」で自作MCPサーバーを爆速開発・導入する手順

近年、AIエージェントにローカル環境のファイルを操作させたり、社内の独自システムと連携させたりするニーズが急速に高まっています。それを実現する業界標準プロトコルとして注目されているのが、Anthropic社が提唱した「Model Context Protocol (MCP)」です。

しかし、一からMCP規格に準拠したサーバーを実装しようとすると、JSON-RPCの通信仕様やセッション管理などの複雑な処理を考慮しなければならず、開発のハードルが高くなっていました。

そこで登場したのが、Python向けのハイレベルフレームワークである「FastMCP」です。FastMCPを使用すれば、従来の複雑な実装を大幅に簡略化し、Pythonのデコレータを数行追加するだけで、AIエージェントから呼び出せる独自ツールを簡単に作成できます。2026年現在、自作のMCPサーバー構築におけるデファクトスタンダードとして広く活用されています。

この記事では、PythonとFastMCPを使用して自作MCPサーバーを構築し、Claude DesktopやClineなどのAIクライアントと連携するまでの全手順を、初心者の方でも迷わないように詳しく解説します。

この記事で行うこと

この記事では、以下のステップに沿って作業を進めます。

  • uvを使用したPython開発環境の構築とFastMCPのインストール
  • Pythonによるシンプルな自作MCPサーバーの実装
  • MCP Inspectorを使用したWebブラウザ上でのデバッグと動作検証
  • Claude DesktopおよびVSCode拡張機能「Cline」への自作MCPサーバーの登録
  • 安全に運用するための注意点とトラブルシューティングの解説

これらの手順を進めることで、AIエージェントがローカルコンピュータ上の情報やカスタム関数を直接実行できるようになります。

前提条件

作業を進めるにあたり、以下の開発環境があらかじめ準備されていることを前提とします。

項目要件
OSWindows 11（macOSやLinuxでも同様に実行可能）
Pythonバージョン 3.10 以上
クライアントClaude Desktop または VSCode（Clineなどの拡張機能を導入済み）
開発ツールuv（推奨パッケージマネージャー）および Node.js（デバッグツール起動用）

Node.jsはデバッグツールであるMCP Inspector（npxコマンド経由）を実行するために使用します。インストールされていない場合は、あらかじめ公式サイトなどから最新のLTS版を導入しておいてください。

手順1：開発環境の準備

まずは、Pythonの開発環境を準備します。本記事では、パッケージのインストールや仮想環境の管理が劇的に速くなる「uv」を使用した手順を推奨します。

コマンドプロンプトまたはPowerShellを起動し、プロジェクトを作成したい任意のディレクトリに移動して以下のコマンドを実行します。

Windows環境でuvが未インストールの場合は、PowerShellから以下のコマンドを実行してインストールします。

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

インストールが完了したら、コマンドプロンプトやPowerShellを再起動し、新しいプロジェクト用のフォルダを作成して初期化します。

mkdir my-mcp-server
cd my-mcp-server
uv init

プロジェクトフォルダ内に pyproject.toml や hello.py などの基本ファイルが生成されます。続いて、FastMCPライブラリを追加します。以下のコマンドを実行してください。

uv add fastmcp

これで、FastMCPを使った開発の準備が整いました。

手順2：PythonによるMCPサーバーの実装

次に、自作のMCPサーバーの本体となるPythonスクリプトを作成します。

プロジェクトフォルダ内に server.py というファイルを作成し、以下の内容を記載します。

import datetime
from fastmcp import FastMCP

# MCPサーバーのインスタンスを作成します
mcp = FastMCP("My Custom Server")

# ツール1：現在時刻の取得
@mcp.tool()
def get_current_time() -> str:
    """現在のサーバーのローカルシステム時刻を返します。"""
    return datetime.datetime.now().strftime("%Y-%m-%d %H:%M:%S")

# ツール2：2つの数値の加算
@mcp.tool()
def add_numbers(a: float, b: float) -> float:
    """2つの数値 a と b を足し合わせた結果を返します。"""
    return a + b

if __name__ == "__main__":
    # サーバーを標準入出力（stdio）モードで起動します
    mcp.run()

実装のポイント

  • FastMCPのインスタンス生成 FastMCP(“My Custom Server”) によってサーバーの初期化を行います。引数に渡した文字列がクライアント側に表示されるサーバー名になります。
  • デコレータによるツールの登録 @mcp.tool() デコレータを付与するだけで、その関数が自動的にMCPの「ツール」として公開されます。関数のDocstring（トリプルクォーテーションで囲まれた説明文）は、AIエージェントが「このツールをいつ、どのような目的で使用すべきか」を判断するための説明として使われます。そのため、説明文は丁寧かつ具体的に記述してください。
  • 型ヒントの指定 関数の引数と返り値には必ず型ヒント（a: float や -> float など）を記述してください。FastMCPは型ヒントを元に自動でJSONスキーマを生成し、クライアントへツールの仕様を伝達します。

手順3：MCP Inspectorを使ったデバッグ手法

サーバーのコードが書けたら、AIクライアントに接続する前に単体でデバッグを行います。MCPには「MCP Inspector」という公式のデバッグ用Webツールが用意されており、これを使うことでツールの動作検証を簡単に行えます。

プロジェクトフォルダのディレクトリで、以下のコマンドを実行します。

npx @modelcontextprotocol/inspector uv run server.py

コマンドを実行すると、ターミナルに以下のような出力が表示され、自動的にブラウザでデバッグ画面（通常は http://localhost:6274）が開きます。

Starting MCP Inspector...
Web UI is available at http://localhost:6274

ブラウザの画面を開くと、実装した「get_current_time」や「add_numbers」がツール一覧に表示されていることが確認できます。

画面上のツール名をクリックし、パラメータを入力して「Call Tool」ボタンを押すことで、Pythonコードが実行され、結果がJSON形式で表示されます。エラーが発生した場合はエラーログも画面上で確認できるため、まずはここで意図通りに動作するかを確認しましょう。

検証が終わったら、ターミナルで Ctrl + C を押してInspectorを終了します。

手順4：クライアント（Claude Desktop / Cline）との連携設定

動作確認ができたら、いよいよAIクライアントと連携させます。ここでは「Claude Desktop」と「VSCodeのCline拡張機能」の2つの設定方法を解説します。

Claude Desktopとの連携設定

Claude Desktopの設定ファイルを編集して、自作MCPサーバーを登録します。

Windowsの場合、エクスプローラーのアドレスバーに以下のパスを入力して移動します。

%APPDATA%\Claude

このフォルダ内にある claude_desktop_config.json をテキストエディタで開きます。ファイルが存在しない場合は、新規作成してください。

ファイルの mcpServers セクションに、以下のように自作サーバーの設定を追加します。パスはご自身の環境に合わせて絶対パスで記述してください。また、Windowsのパスに含まれるバックスラッシュ（\）は、JSONのルールに従って必ず2つ重ねて（\）エスケープしてください。

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

設定を保存したら、Claude Desktopアプリを完全に終了させてから再起動します（タスクトレイのアイコンを右クリックして「Quit Claude」を選択してから再起動してください）。

起動後、チャット入力欄の右下にコンセントのようなアイコンが表示され、ホバーしたときに「My Custom Server」がアクティブになっていれば成功です。「現在のサーバー時刻を教えてください」とチャットで指示し、AIが自動的に自作ツールを呼び出して現在時刻を答えてくれるかテストしてみましょう。

Cline（VSCode拡張機能）との連携設定

VSCodeでClineを使用している場合は、ClineのMCP設定画面から追加するのが簡単です。

  • VSCodeでClineのチャット画面を開きます。
  • 上部にある設定（歯車マーク）アイコンをクリックします。
  • MCPの設定項目にある「Edit MCP Config」をクリックします（または、OSごとの設定ファイル %APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json を直接開きます）。
  • 先ほどのClaude Desktopと同様に、以下のJSONコードを追加して保存します。
{
  "mcpServers": {
    "my-custom-server": {
      "command": "uv",
      "args": ["run", "--directory", "C:\\path\\to\\my-mcp-server", "server.py"]
    }
  }
}

保存すると、Clineが自動的に設定を読み込み、チャット画面の下部に接続されたMCPサーバー名が表示されます。

注意点とトラブルシューティング

破壊的操作やデバッグ出力に注意

  • print() で標準出力に文字列を書き出すと、MCP の JSON-RPC データが破壊されます。デバッグは sys.stderr または logging を使用してください。
  • 破壊的なツール（例: ファイル削除）を実装する場合は、必ず対象ディレクトリを制限し、ユーザー確認ステップを挟むように設計してください。

自作MCPサーバーを構築・運用するうえで、以下の点に注意してください。

1. デバッグ時に print() を使用しない

Pythonでデバッグを行う際、つい print("debug log") のように標準出力へ文字を出力してしまいがちです。しかし、クライアントとMCPサーバーの通信（stdioモード）は標準入出力を介して行われています。

そのため、プログラム内で直接標準出力へ文字列を書き出すと、JSON-RPCのプロトコルデータが破損し、クライアント側で「接続エラー」や「パースエラー」が発生します。

ログやデバッグ情報を出力したい場合は、標準エラー出力（sys.stderr）に書き出すか、Pythonの標準ライブラリである logging を使用してください。また、FastMCPではコンテキストオブジェクトを使用して安全にログを送ることも可能です。

2. セキュリティと実行権限の制限

自作のMCPサーバーは、AIエージェントにローカルマシンの操作権限を与えることになります。例えば、「指定されたフォルダ内のファイルを削除する」ツールなどを不用意に実装すると、AIが誤って重要なシステムファイルを削除してしまうリスクがあります。

  • 操作対象となるディレクトリを特定のフォルダ配下に制限する（パスのバリデーションを徹底する）
  • 破壊的な操作を行うツールの実装は避けるか、事前にユーザーの確認ステップを挟む

などのセキュリティ対策を講じてください。

3. ローカル実行（stdio）とリモート連携（SSE）の違い

本記事で解説した構成は、同じパソコン上でクライアントとサーバーを実行して標準入出力で通信する「stdio」転送方式です。個人利用や開発段階ではこの方式が最も手軽で安全です。

一方、作成したMCPサーバーをサーバーマシン上でホストし、ネットワーク経由で複数のクライアントから利用したい場合は、Server-Sent Events（SSE）を利用したHTTPサーバー化が必要になります。FastMCPでは、起動コマンドを変更するだけで簡単にSSEに対応させることも可能ですが、その際は通信の暗号化（HTTPS）や認証機能の設計が必須となる点に留意してください。

よくある質問

Q. 設定ファイルを追加したのにClaude Desktopでツールが認識されません。

A. 主に以下の原因が考えられます。

  • Claude Desktopが完全に再起動されていない。ウインドウを閉じるだけでなく、タスクトレイから完全にアプリを終了（Quit）させてから起動し流してください。
  • claude_desktop_config.json 内のパス指定に誤りがある。特にWindows環境では \ を \\ にエスケープしているか、絶対パスになっているかを再度確認してください。
  • uv コマンドへのパスが通っていない。設定ファイルの command に直接 uv の絶対パス（例：C:\\Users\\ユーザー名\\.local\\bin\\uv.exe）を指定してみてください。

Q. ツールの説明文は日本語で書いても問題ありませんか？

A. はい、全く問題ありません。関数のDocstringに日本語で説明を記述しておけば、AIエージェントはその日本語の説明を正確に理解してツールを適切に選択・実行してくれます。

まとめ

PythonのFastMCPを使うことで、以前に比べて非常に少ないコード量で、動作する自作MCPサーバーを立ち上げられるようになりました。型ヒントからスキーマが自動生成される仕組みや、MCP Inspectorによる手軽な動作検証など、開発体験も非常に優れています。

日頃のルーティン作業を自動化するカスタムツールや、ローカルの開発環境と連携した高度なAIエージェント構築に向けて、ぜひ自分だけのMCPサーバーを作ってみてください。

参考情報