Claude MCPをPythonで使う入門ガイド｜公式SDK（mcp）とFastMCPでオリジナルAIツールを自作してみた

ClaudeとPythonをMCPでつなぐ：この記事でわかること

「ClaudeってAPIで使えるのはわかったけど、自分のツールやデータベースとつなげるのがめちゃくちゃ面倒」――そう感じていたところ、MCPというキーワードが目に入ってきた。調べてみたら、要するにClaudeと外部ツールをつなぐ”共通規格”で、Pythonでサーバーを書くだけでClaudeがそのツールを使えるようになるらしい。実際に手を動かしてみたら想像以上に簡単だったので、入門としてまとめておく。

• MCPとは何か・なぜ必要なのかがわかる
• MCPの3つの中心概念（Tools / Resources / Prompts）がわかる
• Python（公式SDKのFastMCP、または独立版FastMCP）でMCPサーバーを実際に作れる
• Claude Desktop（またはClaude Code）と接続する方法がわかる
• セキュリティ上の注意点を把握できる

MCP（Model Context Protocol）とは何か：Pythonで使う前に理解したい基礎知識

一言で言うと「AIのためのUSB-Cポート」

MCPはAnthropicが作った標準化されたプロトコルで、AIモデルが統一されたインターフェースを通じてツール、API、外部データソースとやり取りできるようにするものだ。よく「AIのためのUSB-Cポート」と表現される。どんなデバイスもUSB-Cという共通規格でつながるように、ひとつのMCPサーバー実装が複数のMCPクライアントで動くので開発の重複を減らせるし、MCP対応クライアント同士なら接続先を差し替えやすくなるというわけだ。

MCPはAnthropicにより2024年11月に公開された。以降、対応クライアントやサーバー実装が増えており、仕様としてはstdio（標準入出力）/ SSE（Server-Sent Events）/ Streamable HTTP といった標準トランスポートをサポートする。対応状況は日々変化しているため、最新情報は公式ドキュメントで確認してほしい。

MCPがなかった時代は何が辛かったのか

各サービスプロバイダーはAPIを異なる仕様で構築しているため、ツールのわずかな変更がAIワークフロー全体の崩壊を招くことがあった。エンジニアがツール接続を手動で構築・デバッグし、APIキーやツール権限などの認証を管理するのに多大な開発工数がかかっていた。MCPはその手間を減らすための「共通の接続面」を提供する仕組みだ。

MCPアーキテクチャのざっくり全体像

MCPのアーキテクチャは「MCPサーバー」「MCPクライアント」「MCPホスト」の3要素で構成される。

• MCPサーバー：ツール・リソース・プロンプトを提供し、AIモデルが活用できる機能を公開する（自分が実装するもの）
• MCPクライアント：ホストからの指示を受けてサーバーと通信する中間レイヤー
• MCPホスト：Claude DesktopやMCP対応IDEのように、クライアントとサーバー間の通信を管理するランタイム環境

流れを一言でまとめると「ホスト（Claude Desktopなど）→ クライアント → サーバー（自分が作るもの）」だ。サーバーはデータベースアクセス、ファイル操作、API連携などの機能を提供し、クライアントのリクエストに応じてツール・リソース・プロンプトを返す。

MCPの3つの中心概念：Tools / Resources / Prompts

Tools（ツール）：AIが呼び出せる関数

ToolsはAIが実行できる関数のようなもの。LLMが呼び出せる実行可能なコマンドで、add_task・send_an_email・query_a_database などが典型的な例だ。Web APIで言うPOSTエンドポイントに近いイメージで捉えると理解しやすい。

Resources（リソース）：データを読み取るための仕組み

Resourcesはデータへの読み取りアクセスを提供する。Web APIのGETエンドポイントに近いイメージで使われることが多い（ただし設計次第で柔軟に扱える）。タスク一覧、設定ファイル、ユーザープロフィールなどが代表的な例として挙げられる。

Prompts（プロンプト）：テンプレートで会話パターンを定義する

Promptsはユーザーが特定のタスクを達成するのに役立つ事前作成テンプレートだ。繰り返し使うような質問パターンをあらかじめ定義しておける機能で、チームで共有すると便利。

Python環境構築：MCP入門のための準備手順

必要なもの

Pythonは3.10以上を推奨。パッケージ管理には uv を使う方法が公式SDK側でも例示されている（もちろんpipでも可）。公式のMCP Python SDK（パッケージ名は mcp）は、stdio / SSE / Streamable HTTP といった標準トランスポートに対応し、MCPプロトコルのメッセージやライフサイクルイベントを処理してくれる。

MCP Pythonサーバーを手早く書くなら、まずは公式SDKに含まれる mcp.server.fastmcp の FastMCP が便利だ。なお、FastMCPには「公式SDKに同梱されているもの」とは別に、より機能が拡張された独立プロジェクト版FastMCP（pip install fastmcp）もある。どちらを使うかは目的次第で選べる。

Pythonプロジェクトのセットアップ手順

まずuvでプロジェクトを作り、必要なパッケージをインストールする。

# プロジェクトディレクトリを作成
uv init my-mcp-server
cd my-mcp-server

# 仮想環境を作成して有効化
uv venv
source .venv/bin/activate  # Windowsの場合: .venv\Scripts\activate

# MCPをインストール（[cli]で開発用CLIも入る）
uv add "mcp[cli]" httpx

# サーバーファイルを作成
touch server.py

pipでもインストールできるが、uvを使った手順が公式SDK側でも案内されている。

PythonでMCPサーバーを実際に作る：コード解説

まずは最小構成のMCPサーバーから

公式SDK同梱のFastMCPを使えば、Pythonのデコレーター（関数の直前に @ で記述する構文で、関数に機能を追加する仕組み）を使ってシンプルにツールを定義できる。型ヒント等からスキーマ生成が自動で行われるのも便利な点だ。以下が最小構成の例だ。

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

# MCPサーバーのインスタンスを作成（名前は何でもOK）
mcp = FastMCP("MyServer")

# @mcp.tool() デコレーターをつけるだけでツールになる
@mcp.tool()
def add(a: int, b: int) -> int:
    """2つの数を足し算して返す"""
    return a + b

@mcp.tool()
def greet(name: str) -> str:
    """名前を受け取って挨拶文を返す"""
    return f"こんにちは、{name}さん！"

# サーバーを起動（stdioはローカル接続でよく使われるモード）
if __name__ == "__main__":
    mcp.run()

これを動かすには uv run server.py と打てばOK。

Resourcesを追加してデータ読み取りを実装する

次に、AIがデータを「読む」ためのResourcesを追加してみる。デコレーター @mcp.resource("tasks://all") のようにURIライクな識別子でリソースを定義でき、関数はすべてのタスクを読みやすいテキストにフォーマットして返す。

# server.py（続き）

# インメモリのタスクリスト（実際はDBやファイルと連携するイメージ）
tasks = []

@mcp.tool()
def add_task(title: str) -> str:
    """タスクを追加する"""
    tasks.append({"id": len(tasks) + 1, "title": title, "done": False})
    return f"タスク「{title}」を追加しました！"

@mcp.tool()
def complete_task(task_id: int) -> str:
    """タスクを完了にする"""
    for task in tasks:
        if task["id"] == task_id:
            task["done"] = True
            return f"タスクID {task_id} を完了にしました"
    return f"タスクID {task_id} は見つかりませんでした"

# Resource: タスク一覧を公開
@mcp.resource("tasks://all")
def get_all_tasks() -> str:
    """現在のタスク一覧を返す"""
    if not tasks:
        return "タスクはまだありません。"
    result = ""
    for task in tasks:
        status = "✅" if task["done"] else "⬜"
        result += f"{status} [{task['id']}] {task['title']}\n"
    return result

Promptsを加えてテンプレートを定義する

Promptsはサーバーとのやり取り方法をアプリケーションに案内するためのテンプレートだ。タスク分析のためのテンプレートを定義し、参照するリソースをAIに教えることができる。

# server.py（続き）

@mcp.prompt()
def review_tasks() -> str:
    """タスク一覧を分析するためのプロンプトテンプレート"""
    return (
        "tasks://all リソースにアクセスして現在のタスク一覧を確認してください。"
        "未完了のタスクがあれば優先順位をつけてアドバイスしてください。"
    )

Claude DesktopとPythonのMCPサーバーを接続する方法

設定ファイルを編集する（macOS・Windows）

使いたいMCPサーバーに合わせてClaude Desktopを設定する必要がある。macOSの場合、テキストエディタで ~/Library/Application Support/Claude/claude_desktop_config.json を開く。存在しなければ作成する。

設定ファイルに以下を書き込む。/ABSOLUTE/PATH/TO の部分は自分の環境に合わせた絶対パスに変えること。

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/my-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

Windowsの場合の設定ファイルは、従来 %APPDATA%\Claude\claude_desktop_config.json として案内されることが多い。ただし保存場所はアプリの更新で変わる可能性があるため、見つからない場合はClaude Desktopの「Developer（開発者向け）」設定から設定編集（Edit Config）の導線を探すのが確実だ。設定変更後はClaude Desktopを完全に終了・再起動すること。

Claude CodeのCLIからMCPサーバーを追加する

Claude Codeを使っているなら、CLIでMCPサーバーを追加できる。スコープやトランスポートのオプションは環境・バージョンにより変わりうるため、claude mcp add --help で最新のオプションを確認してから使うのが安全だ。

# 例：stdioトランスポートでローカルサーバーを追加（スコープはuserの例）
claude mcp add --transport stdio --scope user my-mcp-server -- uv --directory /path/to/my-mcp-server run server.py

また、Claude CodeはJSON設定を直接追加する add-json や、Claude Desktopからのインポート機能も提供されている。プロジェクト単位の設定の保存場所はツール更新で変わることがあるため、claude mcp get / claude mcp list コマンドで確認する運用が安全だ。

動作確認：MCP InspectorとClaude Desktopで動かしてみる

MCP Inspectorでデバッグする

Claude Desktopに接続する前に、MCP Inspector（公式の開発用デバッグツール）でサーバー単体の動作確認ができる。以下のコマンドで起動する。

# 開発モードで起動（MCP Inspector）
uv run mcp dev server.py

起動後に表示される案内に従ってブラウザでInspectorにアクセスし、UIから直接ツールを叩いて挙動を確認できる。アクセス先のURLは実行環境・バージョンで変わりうるので、必ず起動ログに出るURLを確認してほしい。

Claude Desktopで実際に使ってみる

設定ファイルの保存とClaude Desktopの再起動ができたら、チャット画面から普通に話しかけるだけでツールを呼び出してくれる。たとえば「タスクに『ブログを書く』を追加して」と言えばadd_taskが、「いまのタスク一覧を教えて」と言えばResourceが呼ばれる。今回作ったサーバーは単純な例だが、同じ原則を使ってさまざまなAPIやデータソースと連携する独自のMCPサーバーを構築できる。

MCPのセキュリティ：Python製サーバーを本番で使う前に確認すること

ツール実行の承認フローは実装に依存する

ツール呼び出し時の承認（human-in-the-loop：人間が確認・承認するステップを挟む設計）は推奨事項として示されているが、実際の確認UIや挙動はホスト・クライアントの実装に依存する。本番運用では、どのツールが公開され、いつ実行されるかがユーザーに明確に分かる構成になっているかを必ず確認してほしい。

サードパーティ製MCPサーバーは慎重に選ぶ

MCPサーバーを探すなら、公式のMCP Registryに掲載されているものを起点にすると探しやすい。stdio形式のローカルMCPサーバーはローカル実行権限で動くため、悪意あるサーバーはアクセス可能な範囲の情報に触れられる。サードパーティ製サーバーの利用時は、提供元・権限・挙動（どんなファイルやネットワークにアクセスするか）を必ず確認しよう。

APIキーは環境変数で安全に管理する

トークン類はコードにハードコードせず、環境変数を使うこと。Claude DesktopのMCPサーバー設定では "env" キーで環境変数を渡せる。ただし設定ファイル内に秘密情報を直書きすると、ファイル自体が漏えいリスクになる。OS側で環境変数を設定した上で参照するだけにするか、.env ファイルで別管理する運用が望ましい。

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "uv",
      "args": ["--directory", "/path/to/my-mcp-server", "run", "server.py"],
      "env": {
        "MY_API_KEY": "可能ならここに直書きせず、別経路で安全に渡す"
      }
    }
  }
}

まとめ：Claude MCPをPythonで使う入門ガイド

• MCP（Model Context Protocol）はAnthropicが2024年11月に公開したオープンな標準規格で、ClaudeなどのLLMと外部ツール・データを統一的につなぐ仕組み。
• 3つの中心概念はTools（実行）、Resources（データ提供）、Prompts（テンプレート）。この3つを押さえると設計がスムーズになる。
• PythonでのMCP入門は公式SDK（mcp）のFastMCPが手軽。さらに機能を求めるなら独立版FastMCP（fastmcp）も選択肢になる。
• Claude Desktop / Claude Codeとの接続は設定ファイルまたはCLIで行える。ファイル保存場所やオプションは更新で変わりうるため、公式ドキュメントとCLIのヘルプで確認するのが安全。
• セキュリティは公開するツールの設計、権限の見直し、APIキーの安全管理、サードパーティサーバーの精査が重要。

MCPは仕組みを理解してしまえば「Pythonの関数を書いて公開する」感覚で進められる。まずはシンプルなツールをひとつ作ってClaude DesktopやClaude Codeに繋げてみると、拡張のイメージが一気に掴めるはず。参考になれば！