Pythonで自作MCPサーバーを作る — Claudeと連携する最も簡単な方法

自分が書いたPythonコードをClaudeに渡し、専用ツールとして活用できたらどれほど便利でしょうか。モデルコンテキストプロトコル（MCP）を使えば、PC内のファイルやスクリプトをClaudeデスクトップアプリに非常に簡単に接続できます。難しい理論は一旦脇に置いて、Pythonを使って5分で動作する初めてのMCPサーバーを一緒に作ってみましょう。

MCPサーバー、わざわざ作る必要があるのか？

Claudeと対話していると、「このAIがPC内のファイルを直接読み込み、自作の自動化コードも勝手に実行してくれたらいいのに」と切実に思うことがあります。MCPサーバーは、まさにこうした理想を現実にする強力なツールです。

大掛かりなシステムを一から構築する必要は全くありません。普段使っているローカルファイルの整理スクリプトや、簡単なデータ処理ロジックをPythonで書いておくだけで十分です。MCPサーバーを起動した瞬間、作成したPython関数がそのままClaudeデスクトップアプリでクリック一つで実行できる専用ツールへと変身します。

今回は、初心者でも数行のコードでこの魔法のような連携を実現できるPrefectの「FastMCP」ライブラリを使用します。複雑なAPI構造を覚えなくても自作のAI秘書を作れる、最も直感的な方法を見ていきましょう。

FastMCPで5分で始める超小型サーバーコード

以前は複雑な公式SDKコードを一つひとつ書く必要があり、参入障壁が高いものでした。しかし最近では、Prefectが管理するFastMCPフレームワークのおかげで開発が驚くほど簡単になりました。面倒な設定なしで、Python関数一つだけでClaudeに強力な新機能を持たせることができます。

動作原理は非常にシンプルです。普段使っているPython関数の上にデコレータを乗せるだけで終わりです。FastMCPがPythonの型ヒントや注釈として書かれた説明文を自動的に解析し、Claudeが解釈して実行できるツール設計図へと変換してくれるからです。

2つの数字を足すだけの超小型ツールサーバーのコードを通して、このプロセスを見てみましょう。以下はFastMCP 4.xバージョンを基準に作成したコードです。

python

from fastmcp import FastMCP

# MathServer라는 이름으로 MCP 서버를 만듭니다
mcp = FastMCP("MathServer")

@mcp.tool()
def add_numbers(a: int, b: int) -> int:
    """두 숫자를 더합니다.

    Args:
        a: 첫 번째 숫자
        b: 두 번째 숫자
    """
    return a + b

コードを見ると、入力引数の横に整数を示す型が指定されており、その下に丁寧な説明文が書かれています。FastMCPはこの情報に基づき、「このツールを使うには数字を2つ送る必要がある」と書かれたAPI仕様書をClaudeにリアルタイムで提供します。

初心者が最もよくするミス：print()を使ってはいけない？

MCPサーバーを自作していると、うまく動いていたコードがClaudeデスクトップに接続した途端に動かなくなり、困惑することがよくあります。犯人はまさに、デバッグのために習慣として使っているprint()関数です。

ローカルのMCPサーバーは、基本的に標準入出力（STDIO）を通じてClaudeと通信します。Claudeはサーバーが標準出力に送る、整理されたデータのみを待機しています。そこに一般的なprint()が不用意に混ざると、メッセージの規格が汚染され、接続が即座に切断されてしまいます。

したがって、開発中に進捗状況を確認したりエラーを追跡したい場合は、必ず標準エラー出力（stderr）を使用しなければなりません。Pythonの標準ライブラリを基準に、正しいログ出力方法と間違った方法を簡単に比較してみましょう。

python

import sys
import logging

# ❌ 잘못된 방법: 표준 출력을 오염시켜 클로드와의 연결을 즉시 끊어지게 만듭니다.
print("데이터를 가져오는 중...")

# ✅ 올바른 방법: 표준 에러로 우회 출력하여 통신을 방해하지 않습니다.
print("데이터를 가져오는 중...", file=sys.stderr)

# ✅ 권장하는 방법: 파이썬의 로깅 모듈은 기본적으로 표준 에러로 안전하게 출력됩니다.
logging.info("데이터를 가져오는 중...")

FastMCP環境では、ツール関数内でContextオブジェクトを受け取り、Claudeアプリの画面に直接ログを表示するさらに高度な機能もサポートしています。しかし複雑な機能の前に、標準出力の流れを邪魔しないという基本ルールさえ守れば、初心者が陥るMCPエラーの半分以上を未然に防ぐことができます。

Claude Desktopに一発で接続・テストする

苦労して作ったサーバーを、いよいよ実際のClaudeデスクトップアプリに連携させる番です。連携方法は、自動インストールコマンドを使うか、設定ファイルを直接修正するかの二通りあります。

最も早くて簡単な方法は、FastMCPが提供する自動インストールコマンドを使うことです。ターミナルで以下のコマンドを実行すれば、自動的に登録されます。

bash

uv run fastmcp install server.py --name "MyServer"

このコマンドを入力すると、FastMCPがClaudeデスクトップの設定ファイルにサーバーを自動で登録してくれます。もし手動で登録したい場合は、設定ファイルを直接編集することも可能です。設定ファイルであるclaude_desktop_config.jsonは、OSに応じて以下のパスに存在します。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

Claudeデスクトップはターミナル環境とは独立して実行されるため、設定ファイルを直接修正する場合は、Python実行ファイルとサーバーのスクリプトを必ず絶対パスで記述しなければエラーが発生します。以下の例のように記述してください。

json

{
  "mcpServers": {
    "my-custom-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "/absolute/path/to/server.py"
      ]
    }
  }
}

アプリに連携させる前に、ツールが正しく動作するか視覚的にテストしたい場合はmcp devコマンドを活用してみてください。ターミナルでmcp dev server.pyを実行すると、Webブラウザ上でサーバーの状態を簡単に確認できるMCPインスペクターのウィンドウが開きます。

ただし、セキュリティ上の注意点が一つあります。最近MCPインスペクターツールで発見されたセキュリティ脆弱性（CVE-2025-49596）のため、最新バージョンではトークン認証が必須化されました。そのため、ローカルで安全にテストするにはターミナルに出力されたリンクの後ろにあるセキュリティトークン（?MCP_PROXY_AUTH_TOKEN=...）を必ず含めてアクセスするか、ローカル単独のテスト環境であればDANGEROUSLY_OMIT_AUTH=trueという環境変数を一時的に指定して実行する必要があります。

自分だけのAIエージェントエコシステムを作る

Pythonの数行のコードでClaudeにカスタムツールを接続する、その第一歩を無事に踏み出せました。これからはリアルタイムの天気情報取得やローカルファイルの要約など、自分の日常生活に本当に必要な実用的な機能を一つずつ追加してみてください。自分の手でツールを与え、実験するAIエージェント作り、思ったよりずっと簡単ですよ。