Python MCP Server Starter Template

Python MCP サーバーのスターターテンプレート

Model Context Protocol (MCP) と MCP Python SDK を使用して Python アプリケーションを作成するためのテンプレートリポジトリです。

特長

• mcp Python SDK（FastMCP）を使用して MCP サーバーを実装します。
• MCP ツール（LLM から呼び出し可能な関数）と リソース（LLM からアクセス可能なデータ）を公開します。
• クリーンでモジュール化されたアーキテクチャ
• ツールとリソースを簡単に登録できます
• カスタマイズ可能なオプションを備えたコマンドラインインターフェース
• 本番環境へのデプロイに対応
• debugpy と VS Code の連携による組み込みのデバッグ機能
• 開発ツールを設定済み（環境とパッケージの管理には uv を使用）
• コンテナーでのデプロイに対応する Docker サポート

はじめに

前提条件

• Python 3.10 以降
• uv（環境とパッケージの管理に推奨）
• MCP Inspector（MCP サーバーのテストとデバッグに推奨されるビジュアルツール）
• [任意] Git
• [任意] コンテナーでデプロイする場合は Docker

インストール

1. クローンするかテンプレートとして使用する： コードを取得します。

   git clone https://github.com/ltwlf/python-mcp-starter.git your-repo-name # または GitHub の「Use this template」ボタンを使用します
   cd your-repo-name
   

2. プロジェクト名を変更する： 中核となるコンポーネントの名前を変更します。

   • hello_mcp_server ディレクトリを、任意の Python パッケージ名（例：my_awesome_mcp）に変更します。
   • （pyproject.toml、README.md、Dockerfile、docker-compose.yml 内の）hello-mcp-server を検索し、プロジェクト名（例：my-awesome-mcp）に置き換えます。
   • （main.py、tests/test_server.py、pyproject.toml の scripts セクションなどの Python のインポート文にある）hello_mcp_server を検索し、新しいパッケージ名に置き換えます。
   • 名前を変更した server.py ファイルの APP_ID を更新します。
   • .vscode/launch.json 設定ファイルを更新し、新しいプロジェクト名とパッケージ名を反映します。

3. 仮想環境を作成する：

   # 仮想環境を作成
   uv venv
   # 環境を有効化（Windows PowerShell）
   .venv\Scripts\Activate.ps1
   # その他のシェルの場合：
   # source .venv/bin/activate  (Linux/macOS)
   # .venv\Scripts\activate.bat (Windows Command Prompt)
   

4. 依存関係をインストールする：

   uv pip install -e ".[dev]"
   

開発用 MCP サーバーの実行

uv run または SDK が提供する mcp CLI ツールを使用して、サーバーを直接実行できます。これにより、MCP Inspector などのツールを使ってテストできます。

stdio モード（MCP Inspector 用）

方法 1：uv run を使用

# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with the script name defined in your pyproject.toml
uv run your-script-name

方法 2：mcp CLI ツールを使用

# Ensure your virtual environment is active first
# Replace 'hello_mcp_server' with your renamed package directory
mcp dev ./your_package_name/server.py

SSE モード

# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with your script name
uv run your-script-name --sse

または、ホストとポートを指定します：

# Ensure your virtual environment is active first
# Replace 'hello-mcp-server' with your script name
uv run your-script-name --sse --host 127.0.0.1 --port 9000

Docker でのデプロイ

ビルドする前に、名前を変更したプロジェクト／パッケージが反映されるよう、Dockerfile と docker-compose.yml を更新します。

# Build and run with Docker Compose
docker-compose up -d

# Or build and run directly with Docker
# Replace 'hello-mcp-server' with your image name
docker build -t your-image-name .
docker run -p 8000:8000 your-image-name

開発

デバッグ

このプロジェクトには、debugpy を使用したデバッグ機能が組み込まれています。MCP サーバーをデバッグする主な方法は 2 つあります：

デバッグモジュールを使用する

このプロジェクトには、デバッグを簡単に行える専用のデバッグモジュールが含まれています：

# Using uv (recommended)
uv run mcp-debug

まず MCP Inspector に接続してください。接続後、VS Code のデバッグ構成 Attach to MCP worker を使用して、デバッガーを接続します。

VS Code の使用

VS Code のデバッグは、複数の起動構成で設定されています。

1. MCP ワーカーにアタッチ - 実行中の MCP サーバーにアタッチします（実行中の mcp-debug にアタッチしてください）
2. MCP サーバーを起動（SSE） - サーバー送信イベントを使用して MCP サーバーを直接起動します

最適な使用方法：

1. まず、ターミナルで uv run mcp-debug を実行します
2. 次に、ブレークポイントを設定するには、「MCP ワーカーにアタッチ」構成を使用して VS Code デバッガーを起動します

注： デバッグを行う前に、uv venv と uv pip install -e .[dev] を実行して仮想環境を設定してください。

3. Python インタープリターを確認します：
   • VS Code が仮想環境の正しい Python インタープリターを使用していることを確認します
   • 必要に応じて、Python 拡張機能の「インタープリターを選択」コマンドでインタープリターを選択します

これらの構成を使用するには：

1. VS Code で「実行とデバッグ」パネルを開きます（Ctrl+Shift+D）
2. ドロップダウンから目的の構成を選択します
3. 再生ボタンをクリックするか、F5 キーを押します

セキュリティに関する考慮事項

• 本番環境ではデバッグモードを決して使用しないでください
• デバッガーは、セキュリティ対策が施されていない場合に悪用される可能性のあるネットワークポートを公開します
• デバッグは、信頼できるネットワーク上、または適切なセキュリティ対策を講じたうえで必ず行ってください

新しいツールの追加

your_package_name/server.py で @mcp.tool() デコレーターを使用して新しいツールを追加します：

# your_package_name/server.py
from mcp.server.fastmcp import FastMCP, Context

mcp = FastMCP("your-app-id") # Ensure APP_ID matches your project

# ... existing tools ...

# Add your new tool
@mcp.tool()
async def my_new_tool(param1: str, param2: int, ctx: Context) -> dict:
    """
    Description of what your tool does.
    Use the ctx object to report progress, log info, or read resources.
    """
    ctx.info(f"Running my_new_tool with {param1=}, {param2=}")
    # Tool implementation
    result = f"Processed {param1} {param2} times"
    await ctx.report_progress(1, 1) # Example progress
    return {"result": result}

新しいリソースの追加

your_package_name/server.py で @mcp.resource() デコレーターを使用して新しいリソースを追加します：

# your_package_name/server.py
from mcp.server.fastmcp import FastMCP

mcp = FastMCP("your-app-id") # Ensure APP_ID matches your project

# ... existing resources ...

# Add resources
@mcp.resource("your-resource-uri")
def your_resource_func():
    """Returns application settings."""
    return {"theme": "dark", "language": "en"}

テスト

tests/test_server.py のインポート文が、名前を変更したパッケージを参照していることを確認してください。

pytest

ライセンス

このプロジェクトは MIT License の下でライセンスされています。詳細は LICENSE ファイルを参照してください。

謝辞

• MCP - Microsoft の Model Context Protocol
• MCP Python SDK - MCP の Python 実装
• MCP Inspector - MCP 通信を調査するツール