python-mcp-server-generator

Python MCP サーバージェネレーター

公式の MCP Python SDK v2 を使用して、Python で Model Context Protocol (MCP) サーバーを作成します。SDK v2 は MCP 仕様リビジョン 2026-07-28 をサポートしています。同じサーバーは、以前のリビジョンを使用するクライアントにも対応します。

ワークフロー

このチェックリストをコピーして、進捗を追跡してください:

• ステップ 1: プロジェクトを作成します。
• ステップ 2: サーバーを記述します。
• ステップ 3: テストを記述します。
• ステップ 4: テストが成功するまで実行します。
• ステップ 5: クライアントを設定します。

ステップ 1: プロジェクトを作成します

次のコマンドを実行します:

uv init --app --no-package project-name
cd project-name
uv add "mcp[cli]>=2,<3"
uv add --dev pytest

次に main.py を削除します。サーバーは server.py に記述します。

• --no-package を指定しない場合、uv は src/ パッケージレイアウトを作成するため、テストが server.py をインポートできません。
• uv init は .gitignore ファイルを作成します。別のものを記述しないでください。

ステップ 2: サーバーを記述します

このテンプレートから始めます:

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("Demo", version="0.1.0")


@mcp.tool()
def divide(a: float, b: float) -> float:
    """Divide a by b."""
    if b == 0:
        raise ToolError("b must not be zero.")
    return a / b


if __name__ == "__main__":
    mcp.run()  # stdio is the default transport

次に、ユーザーのリクエストに合わせてテンプレートを変更します:

1. divide を、ユーザーが必要とするツールに置き換えます。
2. 各ツールに完全な型ヒントと docstring を付けます。SDK は型ヒントから入力スキーマを生成します。docstring はツールの説明になります。
3. クライアントが機械可読なデータを必要とする場合は、Pydantic モデルまたは TypedDict を返します。SDK は戻り値の型から出力スキーマを生成します。
4. I/O には async def を使用します。SDK は同期ツールをワーカースレッドで実行します。
5. 読み取り専用ツールには @mcp.tool(annotations=ToolAnnotations(read_only_hint=True))(mcp.types から)を付けます。破壊的なツールには destructive_hint=True を使用します。
6. リソース(@mcp.resource("users://{user_id}"))とプロンプト(@mcp.prompt())は、ユーザーが要求した場合にのみ追加します。

デフォルトでは stdio を使用します。ユーザーがリモートサーバーまたは HTTP サーバーを要求した場合にのみ、references/streamable-http.md を参照してください。

ステップ 3: テストを記述します

test_server.py を server.py の隣に配置します。各ツールと各 ToolError に対してテストを記述します:

import pytest

from mcp import Client

from server import mcp


@pytest.mark.anyio
async def test_divide():
    async with Client(mcp) as client:
        result = await client.call_tool("divide", {"a": 6, "b": 3})
        assert result.structured_content == {"result": 2.0}


@pytest.mark.anyio
async def test_divide_by_zero():
    async with Client(mcp) as client:
        result = await client.call_tool("divide", {"a": 1, "b": 0})
        assert result.is_error
        assert "must not be zero" in result.content[0].text

• インメモリの Client はサブプロセスもポートも必要としません。2026-07-28 リビジョンで接続します。
• mcp パッケージは anyio をインストールし、これが anyio マーカーを提供します。pytest-asyncio を追加しないでください。

ステップ 4: テストが成功するまで実行します

1. uv run pytest を実行します。
2. テストが失敗した場合は、エラーを読みます。サーバーまたはテストを修正します。
3. uv run pytest を再度実行します。
4. すべてのテストが成功した場合にのみ続行します。

ステップ 5: クライアントを設定します

VS Code の場合は、.vscode/mcp.json を記述します:

{
  "servers": {
    "demo": {
      "type": "stdio",
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/project", "run", "server.py"]
    }
  }
}

Claude Desktop の場合は、uv run mcp install server.py を実行します。

ユーザーに次のコマンドを伝えます:

• uv run server.py は stdio サーバーを起動します。サーバーは stdin でホストを待機し、何も出力しません。
• uv run mcp dev server.py は MCP Inspector を開きます。Inspector には Node.js が必要です。

注意点

SDK v2 と 2026-07-28 リビジョンでは、多くの SDK v1 のパターンが変更されました。SDK v1 の例をコピーしないでください。

• SDK v2 では FastMCP と mcp.server.fastmcp が削除されました。サーバークラスは from mcp.server import MCPServer でインポートします。
• Context、Image、Audio、Resolve、Elicit、ElicitationResult、AcceptedElicitation、Message、UserMessage、AssistantMessage は mcp.server.mcpserver からインポートします。
• サーバー名は MCPServer の最初の引数として指定します。その他のコンストラクター引数はすべてキーワード引数として指定します。これらの位置引数の順序は SDK v2 で変更されました。
• version を設定します。設定しない場合、サーバーは空のバージョンを報告します。
• トランスポートオプション（transport、host、port、json_response、stateless_http、transport_security）は MCPServer(...) ではなく run() に指定します。
• SDK v2 の型は snake_case のフィールドを使用します。例えば read_only_hint、structured_content、is_error です。
• モデルが読む必要のあるエラーには ToolError を発生させます。その他の例外の場合、モデルは一般的なエラーメッセージのみを受け取ります。
• ツールの失敗に対して MCPError を発生させないでください。クライアントは is_error を持つツール結果ではなく、プロトコルエラーを受け取ります。多くのホストはこのエラーをモデルに表示しません。
• stdio サーバーでは、stdout がプロトコルチャネルです。print() を呼び出さないでください。logging モジュールを使用して stderr にログを出力します。
• ctx.elicit() を使用しないでください。2026-07-28 接続では失敗します。ツール呼び出し中のユーザー入力には、パラメーターに Resolve(fn) を注釈として付けます。fn から Elicit(message, Model) を返します。
• リスト変更通知は await ctx.notify_tools_changed() で送信します。2026-07-28 接続では ctx.session.send_tool_list_changed() が削除されています。
• stdio と HTTP では、lifespan はサーバーの起動時に一度だけ実行されます。テスト内の各インメモリ Client(mcp) は lifespan を再度実行します。そのオブジェクトは ctx.request_context.lifespan_context で読み取ります。
• 2026-07-28 リビジョンでは、以下の機能が非推奨になりました（SEP-2577）。新しいサーバーにこれらを追加しないでください:
  • Sampling（ctx.session.create_message()）: LLM プロバイダー API を直接呼び出してください。
  • プロトコルログ（ctx.log()、ctx.info() および同様のメソッド）: 標準の logging モジュールを使用してください。
  • Roots（ctx.session.list_roots()）: ツールパラメーター、リソース URI、またはサーバー設定からパスを取得してください。
• 2026-07-28 リビジョンには SSE トランスポートがありません。Streamable HTTP を使用してください。