Building a Simple MCP Server in Python Using the MCP Python SDK

MCP Python SDK を使用した Python によるシンプルな MCP サーバーの構築

Model Context Protocol（MCP）は、大規模言語モデル（LLM）にコンテキストを提供するための標準化された方法です。MCP Python SDK を使用すると、LLM アプリケーションにデータ（リソース）、機能（ツール）、インタラクションテンプレート（プロンプト）を安全かつモジュール化された方法で公開するサーバーを構築できます。このチュートリアルでは、Python でシンプルな MCP サーバーを段階的に構築します。

はじめに

Model Context Protocol（MCP）は、アプリケーションと LLM の間のインターフェースを標準化します。MCP を使うと、コンテキストの提供、コードの実行、ユーザーとのインタラクションの管理を分離できます。MCP Python SDK は MCP 仕様全体を実装しており、次のことができます。

• リソースを公開する： LLM にデータを提供します（GET エンドポイントに類似）。
• ツールを定義する： アクションや計算を実行する機能を提供します（POST エンドポイントのようなものです）。
• プロンプトを作成する： 再利用可能なテンプレート化されたインタラクションを提供します。

MCP のプリミティブ

すべての MCP サーバーは、3 つのコアプリミティブを実装できます。これらは、呼び出しを誰が制御するかと、各プリミティブがどのような役割を果たすかを定義します。

プリミティブ	制御	説明	使用例
プロンプト	ユーザー制御	ユーザーの選択によって呼び出されるインタラクティブなテンプレート	スラッシュコマンド、メニュー項目
リソース	アプリケーション制御	クライアントアプリケーションが管理するコンテキストデータ	ファイルの内容、API のレスポンス
ツール	モデル制御	アクションを実行するために LLM に公開される関数	API 呼び出し、データ更新

• プロンプトを使うと、_構造化された_会話のきっかけを定義できます。
• リソースは、LLM のコンテキスト用の読み取り専用データエンドポイントのようなものです。
• ツールを使うと、LLM が計算、取得、更新などを実行できます。

---

サーバーの機能

初期化時に、MCP サーバーはサポートする機能を通知します。クライアント（およびフロントエンド）は、これらのフラグに基づいて動的に対応できます。

機能	機能フラグ	説明
prompts	listChanged	プロンプトテンプレートの管理
resources	subscribe listChanged	リソースの公開とライブ更新
tools	listChanged	ツールの検出と実行
logging	–	サーバーのログ設定
completion	–	引数の補完候補

• **listChanged**は、利用可能なプロンプト／リソース／ツールのセットが実行時に変更される可能性があることを示します。
• **subscribe**を使うと、リソースデータが変更されたときに更新を受け取るよう、クライアントが登録できます。
• **loggingとcompletion**は、デバッグ出力とオートコンプリート支援のための単純な切り替え項目です。

このチュートリアルでは、MCP Python SDK を使用してシンプルな MCP サーバーを作成する方法を説明します。

前提条件

始める前に、以下がインストールされていることを確認してください。

• Python 3.7+（できれば 3.11 以上）
• pip – Python パッケージインストーラー
• Node.js 18.x

MCP Python SDK もインストールする必要があります。方法は 2 つあります。

• pip を直接使用する：

  pip install "mcp[cli]"
  

• uvを使用する：
  uvでプロジェクトを管理している場合は、プロジェクトを初期化し、依存関係として MCP を追加します。

  uv init mcp-server
  cd mcp-server
  uv add "mcp[cli]"
  

インストール方法の詳細については、MCP Python SDK のドキュメントを参照してください。

環境のセットアップ

このセクションでは、Ubuntu 22.04 で Python 3.11 を使用して開発環境をセットアップし、適切な Python バージョンと MCP Python SDK がインストールされていることを確認します。

オプション 1：手動インストール 段階的に進めたい場合は、次の手順に従ってください。

1. deadsnakes PPA を追加します： このリポジトリでは、Ubuntu 向けにより新しいバージョンの Python を提供しています。

   sudo add-apt-repository ppa:deadsnakes/ppa -y
   

2. パッケージリストを更新します：

   sudo apt update
   

3. Python 3.11 と必須ツールをインストールします：

   sudo apt install -y python3.11 python3.11-venv python3.11-distutils python3-apt
   

   • python3.11：Python 3.11 インタープリターです。
   • python3.11-venv：Python 3.11 用の仮想環境モジュールです。
   • python3.11-distutils：Python パッケージのビルドとインストールに必要なツールです。
   • python3-apt：APT パッケージ管理システム用の Python インターフェースです（依存関係に関する問題の解決に役立ちます）。

4. Python 3.11 をデフォルトの python3 に設定します（任意ですが推奨）： これにより、毎回 python3.11 を指定せずに Python 3.11 を簡単に使用できます。

   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.10 1
   sudo update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 2
   sudo update-alternatives --config python3
   

   デフォルトの Python 3 のバージョンを選択するよう求められます。Python 3.11 を選択してください。

5. Python 3.11 用の pip をインストールします： pip は Python のパッケージインストーラーです。

   curl -sS https://bootstrap.pypa.io/get-pip.py | sudo python3.11
   

6. Python と pip のバージョンを確認します：

   python3 --version
   python3 -m pip --version
   

   出力に Python 3.11 と、比較的新しいバージョンの pip が表示されることを確認してください。

7. Node.js 18.x 用に NodeSource を設定しています…

curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -

Node.js をインストールしています（npm と npx を含む）…"

sudo apt-get update
sudo apt-get install -y nodejs

9. 仮想環境を作成して有効化します： 仮想環境を使用すると、プロジェクトの依存関係を分離できます。

   python3 -m venv .venv
   source .venv/bin/activate
   

   プロジェクト内に .venv ディレクトリが作成され、環境が有効になったことを示す (.venv) がターミナルのプロンプトに表示されます。

10. 仮想環境内で pip をアップグレードします：

    pip install --upgrade pip
    

11. MCP Python SDK をインストールします： プロジェクトディレクトリに requirements.txt という名前のファイルを作成し、次の内容を記述します。

    mcp[cli]
    

    次に、pip を使用して SDK をインストールします。

    pip install -r requirements.txt
    

オプション 2：install.sh スクリプトを使用する

より自動化されたセットアップを行うには、付属の install.sh スクリプトを使用できます。

1. スクリプトを保存します： 先ほど提示したスクリプトが、プロジェクトディレクトリに install.sh として保存されていることを確認してください。

2. スクリプトを実行可能にします： ターミナルを開き、プロジェクトディレクトリに移動して、次のコマンドを実行します。

   chmod +x install.sh
   

3. スクリプトを実行します： 次のコマンドを実行します。

   bash install.sh
   

   install.sh スクリプトは、手動でのインストール手順を自動化します。

   • deadsnakes PPA を追加し、パッケージリストを更新します。
   • Python 3.11 と必要なツールをインストールします。
   • Python 3.11 をデフォルトの python3 に設定します。
   • Python 3.11 用の pip をインストールします。
   • .venv という名前の仮想環境を作成して有効化します。
   • 仮想環境内で pip をアップグレードします。
   • Node.js をインストールします：node v18.20.8
   • requirements.txt が存在する場合は、そこから MCP Python SDK をインストールします。

重要な注意事項：

• 選択した方法にかかわらず、新しいターミナルセッションでプロジェクトを作業するたびに、仮想環境（source .venv/bin/activate）を有効にしてください。これにより、正しい Python バージョンを使用し、インストール済みの MCP SDK にアクセスできます。
• install.sh スクリプトは Ubuntu 22.04 向けに設計されています。別のオペレーティングシステムやディストリビューションを使用している場合は、スクリプトを適宜調整する必要があります。
• requirements.txt ファイルは、プロジェクトの依存関係を管理するうえで重要です。必要なパッケージを常に記載しておいてください。

環境の設定が完了したので、MCP サーバーを作成する準備ができました！

---

プロジェクトのセットアップ

プロジェクト用の新しいディレクトリを作成し、その中に移動します。次に、プロジェクトのルートに server.py というファイルを作成します。

プロジェクトの構成は次のようになります。

mcp-server/
├── server.py
└── (other files such as .env, README.md, etc. as needed)

MCP サーバーの作成

このセクションでは、計算ツールと動的な挨拶リソースを公開するシンプルな MCP サーバーを作成します。後からプロンプトや追加のツールを使って、機能を拡張できます。

ツールの定義

ツールは、計算や副作用を伴う処理を実行する関数です。この例では、シンプルな加算ツールを定義します。

server.py を開き、次のコードを追加します。

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

# Create an MCP server instance with a custom name.
mcp = FastMCP("Demo Server")

# Add a calculator tool: a simple function to add two numbers.
@mcp.tool()
def add(a: int, b: int) -> int:
    """
    Add two numbers together.
    
    :param a: First number.
    :param b: Second number.
    :return: Sum of the numbers.
    """
    return a + b

リソースの公開

リソースは、LLM のコンテキストに読み込めるデータを提供します。ここでは、個人に合わせた挨拶を返すリソースを定義します。

次のコードを server.py に追加します。

# Expose a greeting resource that dynamically constructs a personalized greeting.
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """
    Return a greeting for the given name.
    
    :param name: The name to greet.
    :return: A personalized greeting.
    """
    return f"Hello, {name}!"

プロンプトの追加（任意）

プロンプトを使うと、やり取りに再利用可能なテンプレートを提供できます。たとえば、コードをレビューするプロンプトを追加できます。

必要に応じて、次のコードを追加します。

from mcp.server.fastmcp.prompts import base

@mcp.prompt()
def review_code(code: str) -> str:
    """
    Provide a template for reviewing code.
    
    :param code: The code to review.
    :return: A prompt that asks the LLM to review the code.
    """
    return f"Please review this code:\n\n{code}"

MCP サーバーの実行

まず、次を実行して Python の仮想環境が有効になっていることを確認します。

source .venv/bin/activate

これはプロジェクトのルートディレクトリで実行してください。次に、MCP サーバーのフォルダーに移動します。

cd mcp-server

server.py でサーバーを定義したら、実行できるようになります。MCP サーバーの実行方法はいくつかあり、開発、デバッグ、統合、デプロイのどれを目的とするかによって異なります。

サーバーの実行とテストに最適な方法：mcp dev を使う

MCP サーバーを操作する最も簡単な方法は、ブラウザー上で視覚的な UI を提供する、組み込みの MCP Inspector を使うことです。

開発とテストには、サーバーを操作するための直感的なウェブインターフェースを備えた MCP Development Inspector を使用できます。

1. 開発モードでサーバーを起動する

ターミナルで次を実行します。

mcp dev server.py

このコマンドを実行すると、MCP サーバーが起動し、通常はブラウザーで Inspector が開きます。「Demo Server」と、公開されているツール（add）、リソース（greeting）、プロンプト（review_code）が表示されます。

1. Inspector を使ってサーバーを起動します。

   mcp dev server.py
   

2. 次の重要な処理が実行されます。

• デフォルトの STDIO トランスポートを使ってMCP サーバーを起動します。
• ライブリロードを有効にするため、サーバーを再起動しなくてもコードの変更がすぐに反映されます。
• MCP Inspector インターフェースを起動します。これは http://localhost:6274/ で利用できるウェブベースの UI で、サーバーのすべての機能を確認してテストできます。

コマンドを実行すると、ターミナルには次のような出力が表示されます。

この出力は、Inspector が有効で、操作できる状態であることを示しています。

1. UI では、次の操作を行えます。
   • add(a, b) ツールをテストする
   • greeting://John を使ってリソースをテストする
   • review_code プロンプトを使ってコードをレビューする

💡 パッケージが不足している場合、mcp dev が自動インストールをサポートします。

MCP Inspector インターフェースの操作

2. Inspector を通じて操作する

ブラウザーで Inspector を開くと、サーバーのテストを容易にするためのいくつかの重要なセクションが表示されます。

MCP Inspector のインターフェース上部に移動すると、次のように表示されます。

Transport Type: STDIO  
Command: python  
Arguments: run --with mcp mcp run server.py

server.py は通常の pip ベースの仮想環境を使用するスタンドアロンのスクリプトであるため、MCP Inspector の設定を次のように修正する必要があります。

Transport Type: STDIO  
Command: python  
Arguments: server.py

次に Connect をクリックすると、Python インタープリターを使ってサーバーが正しく起動します。

使用例：「Add」ツールをテストする

• ツール（add）を呼び出す： Inspector で add ツールに移動します。

加算ツール、挨拶リソース、コードレビュー用プロンプトを登録する例を使って作業する場合、次のシナリオを参考にしてください。

1. Tools タブにアクセスする：
   MCP Inspector を読み込んだら、Tools タブに移動します。List Tools をクリックします。ここには、サーバーに登録されたすべてのツールの一覧が表示されます。この例では、そのうちの 1 つが add ツールです。

2. 「Add」機能をテストする：
   一覧から add ツールをクリックします。Inspector にツールの入力スキーマが表示され、2 つの数値（たとえば、パラメーター a と b）の入力を求められます。

   • 入力パラメーター： a = 10、b = 15 を入力します。
   • 実行： Inspector の実行パネルにある実行ボタンをクリックします。

3. 出力を確認する：
   実行すると、Inspector に操作の結果がすぐに表示されます。合計が 25 として返されるはずです。
   この即時のフィードバックにより、開発インターフェースを離れることなく、ツールのロジックが想定どおりに動作するかをすばやく確認できます。

MCP Inspector で review_code プロンプトを使う

• Inspector のサイドバーで、Prompts → List prompts を展開します。
• 一覧に review_code が表示されます：

  review_code

プロンプトペインには、引数を入力できるフォームまたは JSON エディターが表示されます。

2. code パラメーターを指定します。 例：

print(1+1)

Run Tool をクリックします。

生成されたプロンプトを表示する

Inspector に出力が表示されます：

{
  "messages": [
    {
      "role": "user",
      "content": {
        "type": "text",
        "text": "Please review this code:\n\nprint(1+1)"
      }
    }
  ]
}

リソースにアクセスする（greeting://Alice）

上記の設定を使用して Inspector でサーバーが起動したら、URI を使って登録済みのリソースを呼び出せます：

1. リソース操作ペインを開く

• MCP Inspector のサイドバーで、Resources → Resource Templates をクリックします。 List templates をクリックして、 get_greeting を選択します。

2. リソース URI を入力する

• 入力フィールドに次のように入力します：

Alice

3. リソースを呼び出す

• Read Resource をクリックします。
• Inspector がその URI を @mcp.resource("greeting://{name}") ハンドラーに送信します。

4. 応答を確認する

• 次のように表示されます：

{
  "contents": [
    {
      "uri": "greeting://Alice",
      "mimeType": "text/plain",
      "text": "Hello, Alice!"
    }
  ]
}

• これにより、動的な挨拶リソースが正しく接続され、要求に応じて個別の出力を返すことが確認できます。

MCP Inspector は使いやすいクライアントとして機能し、基盤となるプロトコル通信を代わりに処理します。

python server.py で起きていること

コードは正しいのですが、次のコマンドを実行しても：

python server.py

…何も起きないように見えます。これは、サーバーがデフォルトのトランスポートとして **stdio（標準入力／出力）**を使用しており、クライアントが接続してリクエストを送信するのを、何も表示せずに待機しているためです。

これは正常です！ただし、操作するには適切なインターフェースが必要です。

🐍 Python MCP クライアント（client.py）を使う

プログラムから操作するには、mcp Python SDK を使用してクライアントを作成できます。提供されている client.py は、その正しい例です：

# client.py
import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="python",
        args=["server.py"],
    )

    async with stdio_client(server_params) as (reader, writer):
        async with ClientSession(reader, writer) as session:
            await session.initialize()

            result = await session.call_tool("add", arguments={"a": 3, "b": 4})
            print(f"Result of add tool: {result}")

if __name__ == "__main__":
    asyncio.run(main())

このクライアントを実行するには：

1. サーバーを起動します：

   python server.py
   

2. 別のターミナルでクライアントを実行します：

    python client.py

出力は次のとおりです：

[your log output indicating the tool call]
Result of add tool: meta=None content=[TextContent(type='text', text='7', annotations=None)] isError=False

これにより、Python クライアントがサーバーに接続し、プログラムからツールを呼び出す方法がわかります。

まとめ

このチュートリアルでは、MCP Python SDK を使って、シンプルな MCP サーバーを Python で構築しました。以下を行いました。

• プロジェクトをセットアップし、MCP SDK をインストールしました。
• 計算ツールと動的な挨拶リソースを公開する MCP サーバーを作成しました。

MCP Python SDK を活用すると、LLM アプリケーションにデータ、機能、再利用可能なインタラクションテンプレートを提供する、堅牢でモジュール化されたサーバーを構築できます。サーバーを拡張する際は、Model Context Protocol の力を最大限に活用するため、より複雑なツール、リソース、プロンプトを追加することを検討してください。