MCPサーバーを自作してClaudeをもっと賢くする！PythonでカスタムAIツールを作る入門ガイド

MCPサーバーとは？仕組みと自作するメリット

Model Context Protocol（MCP）を10秒で理解する

「Claudeにもっとできることをさせたいけど、プラグインの作り方がわからない」と感じたことはありませんか？そのカギを握るのが、Anthropicが2024年11月に公開したModel Context Protocol（MCP）です。

MCPとは、AIモデルと外部ツール・データソースをつなぐための標準通信規格（プロトコル）です。USB-Cポートのようなもの、と考えるとわかりやすいでしょう。どんなデバイスでもUSB-Cがあれば接続できるように、MCPに対応していれば任意のツールをClaudeに接続できます。

ローカル環境でMCPサーバーを安定稼働させたい場合は、Raspberry Pi 5（8GBモデル）が有力な選択肢のひとつです。省電力で24時間運用できる点が多くのエンジニアに支持されており、ぜひスペックを確認してみてください。

既存のAIツールと自作MCPサーバーの違い

ChatGPTのプラグインやClaude.aiのデフォルト機能は便利ですが、あくまで「用意されたものを使う」にとどまります。一方、自作MCPサーバーは自分のビジネス・ワークフロー専用のツールを一から設計できる点が決定的に異なります。

自作することで広がる3つの可能性

MCPサーバーを自作すると、できることの幅が一気に広がります。具体的には次の3点が大きなメリットです。

実際、国内外のエンジニアコミュニティでは「業務効率が1.5〜2倍になった」という報告も増えています。次のセクションでは、Pythonを使って実際に手を動かしながら自作の第一歩を踏み出してみましょう。

開発環境の準備と必要なツール一覧

「環境構築でつまずいて、結局そこで挫折してしまった」という経験はありませんか？MCPサーバー開発はツールの数が多いため、最初の準備を丁寧に済ませておくことが成功の鍵です。ここでは躓きやすいポイントを先回りして解説します。

Pythonバージョンと推奨ライブラリの確認方法

MCP SDKはPython 3.10以上を要件としており、2026年現在の推奨バージョンは3.12系です。まず以下のコマンドで手元の環境を確認しましょう。

python --version

3.10未満だった場合はアップグレードが必要です。macOSならpyenv、Windowsなら公式インストーラーを使うとバージョン管理が格段に楽になります。

あわせて、以下のツールも事前に揃えておくとスムーズです。

• pip または uv（パッケージ管理ツール）
• venv または conda（仮想環境）
• VS Code ＋ Python・Pylance 拡張機能
• Git（サンプルコードの取得に使用）

Claude DesktopとMCP SDKのインストール手順

MCPサーバーをClaudeに接続するには、Claude Desktopアプリが必要です。2026年現在、Windows・macOS向けに無料で公開されています。インストールから接続登録まで、3ステップで完了します。

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

pip install mcp

動作確認に使うサンプルプロジェクトの準備

いきなりオリジナルのサーバーを作るより、まず公式サンプルで「動く状態」を確認しておくことを強くおすすめします。後のトラブルシューティングで「環境の問題か、コードの問題か」を切り分けられるようになるためです。

pip show mcp  # インストール確認
python -c "import mcp; print(mcp.__version__)"

from mcp.server import Server
from mcp.server.stdio import stdio_server

app = Server("hello-mcp")

@app.list_tools()
async def list_tools():
    return []

if __name__ == "__main__":
    import asyncio
    asyncio.run(stdio_server(app))

長時間のコーディング作業を快適にするキーボード選びも、開発効率を大きく左右する要素のひとつです。静音性と打鍵感を両立したHHKB Professional HYBRID Type-Sは、MCPサーバー開発のような集中力を要する作業との相性がよいといわれていますので、ぜひチェックしてみてください。

開発環境を整える際、ポート不足に悩んだことがある場合は、Anker USB-C ハブ 7-in-1もあわせて確認してみてください。MCPサーバーの自作では外部機器を接続する場面が増えるため、ハブひとつで作業効率が変わってくることも少なくありません。

MCPやLLMの仕組みをもっと深く理解したい場合は、『大規模言語モデル入門』（技術評論社）もあわせて確認してみてください。トークン化からファインチューニングまで、実装ベースで学べる一冊です。

最小構成のMCPサーバーを作ってみる

環境構築が完了したら、いよいよ実装に入りましょう。「まず動くものを作る」が上達への近道です。ここでは「Hello World」相当のシンプルなMCPサーバーを1ファイルで完成させ、Claudeとの通信の流れを体感します。

server.pyの基本コード構造とポイント解説

プロジェクトルートに server.py を作成し、以下のコードを入力してください。全体で約40行、初めて読む場合でも10分あれば理解できる分量です。

from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types
import asyncio

app = Server("hello-mcp")

@app.list_tools()
async def list_tools() -> list[types.Tool]:
    return [
        types.Tool(
            name="say_hello",
            description="名前を受け取り挨拶を返すツール",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "挨拶する相手の名前"
                    }
                },
                "required": ["name"]
            }
        )
    ]

@app.call_tool()
async def call_tool(name: str, arguments: dict) -> list[types.TextContent]:
    if name == "say_hello":
        return [types.TextContent(
            type="text",
            text=f"こんにちは、{arguments['name']}さん！MCPサーバーから返信しています。"
        )]
    raise ValueError(f"未知のツール: {name}")

async def main():
    async with stdio_server() as (read, write):
        await app.run(read, write, app.create_initialization_options())

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

Claudeからツールを呼び出す仕組みの確認

MCPの通信は「標準入出力（stdio）」を経由したJSON-RPCで行われます。つまり、ClaudeデスクトップアプリとPythonプロセスがパイプでつながっているイメージです。実際の流れは以下の3ステップです。

動作確認は claude_desktop_config.json にサーバーパスを登録してClaudeデスクトップを再起動するだけです。ツールアイコンが表示されれば接続成功、所要時間は2〜3分が目安です。

よくあるエラーと対処法まとめ

初回起動時に詰まるポイントはほぼ決まっています。次の3つを先に確認しておくと、解決時間を大幅に短縮できます。

実用的なカスタムツールの実装例3選

Hello Worldで構造を掴んだら、次はいよいよ実務に直結するツールへとステップアップです。ここでは「ファイル操作」「外部API連携」「データ集計」の3パターンを紹介します。それぞれ50〜100行程度のコードで実装できるため、週末の数時間で十分試せる規模感です。

ローカルファイルを読み書きするツールの作り方

「Claudeに社内ドキュメントを直接参照させたい」と感じたことはありませんか？ファイル操作ツールはその第一歩となります。

読み取りツールではread_file(path: str)、書き込みツールではwrite_file(path: str, content: str)のシグネチャを定義し、それぞれ@mcp.tool()デコレータで登録します。テキストファイルであれば文字コードをUTF-8に統一しておくと、日本語環境でのトラブルを約80%防げるといわれています。

外部APIを叩いてデータを返すツールの実装

天気情報や為替レート、社内REST APIなど、リアルタイムデータをClaudeに渡すユースケースは多岐にわたります。実は、MCPツールからの外部HTTP通信はhttpxライブラリ1つで完結します。

非同期処理（async def）を使うと、タイムアウト設定や複数API並列呼び出しが容易になります。タイムアウトは5〜10秒を目安に設定しておくと、Claudeの応答待ちが長引くストレスを抑えられるでしょう。APIキーは環境変数（os.environ）から取得し、コードにハードコードしないことが鉄則です。

CSVを集計してClaudeに渡すデータ処理ツール

売上データや在庫管理表など、業務の現場ではCSVファイルが今でも主役です。「毎月ExcelでSUM関数を叩いている」という作業をClaudeに任せられると、1回あたり15〜30分の削減が見込めるという報告もあります。

pandasを使えば、CSVの読み込みから集計・フィルタリングまでを20行前後で実装可能です。集計結果はJSON形式（df.to_dict(orient="records")）でClaudeに返すと、そのまま自然言語での分析・コメント生成につなげられます。

• 列名の自動検出で汎用的なツールに仕上げる
• 数値列のみを対象にdescribe()で基本統計量を算出する
• 行数・列数も一緒に返すと、Claudeがデータ規模を把握しやすくなる
• 文字コードはUTF-8とShift-JIS両対応にしておくと業務ファイルで詰まらない

3つのパターンを組み合わせると、「CSVを読み込み→外部APIで補完→結果をファイルに書き出す」という一連の自動化パイプラインをClaudeだけで完結させることも十分可能です。ぜひ自分のユースケースに合わせてカスタマイズしてみてください。

Claude Desktopへの接続と動作テストの方法

ファイル操作やWeb取得ツールを実装したあと、「本当にClaude上で動くのだろうか」と不安に感じたことはありませんか。設定ファイルの記述ミスひとつで接続が失敗するため、手順を正確に押さえておくことが重要です。

claude_desktop_config.jsonの正しい記述方法

Claude Desktopは起動時に設定ファイルを読み込み、MCPサーバーとの接続を確立します。設定ファイルのパスはOSによって異なり、macOSでは~/Library/Application Support/Claude/claude_desktop_config.json、Windowsでは%APPDATA%\Claude\claude_desktop_config.jsonに配置します。

{
  "mcpServers": {
    "my-tools": {
      "command": "python",
      "args": ["/Users/yourname/mcp/server.py"],
      "env": {}
    }
  }
}

仮想環境（venv）を使っている場合は、commandをpythonではなく/Users/yourname/mcp/.venv/bin/pythonのように仮想環境内のPythonパスに変更する必要があります。この設定ミスが接続失敗の原因トップ3に入るといわれています。

Claude上でカスタムツールが呼ばれているか確認する手順

設定ファイルを保存したら、Claude Desktopを完全に再起動します。単なる画面の再表示では設定が反映されないため、プロセスごと終了して再度立ち上げることがポイントです。

ハンマーアイコンが表示されない場合は、設定ファイルのJSON構文エラーが原因であるケースが全体の約7割を占めます。まずJSONバリデーターで構文を確認してみてください。

ログを活用したデバッグの基本

ツールが呼ばれない、エラーが返ってくるといった問題が起きた場合は、ログの確認が最短の解決策です。Claude DesktopのログはmacOSなら~/Library/Logs/Claude/配下に、Windowsなら%APPDATA%\Claude\logs\配下に自動的に出力されます。

一方、サーバースクリプト側にもloggingモジュールでデバッグ出力を仕込んでおくと、ツールの引数受け渡しや処理結果をリアルタイムで追跡できます。本番稼働前にlogging.DEBUGレベルで一度動かし、想定どおりの値が流れているか確認してみてください。

セキュリティとパフォーマンスの注意点

MCPサーバーをClaude Desktopと接続して動作確認できたら、次は「本番運用」を見据えた設計に目を向けましょう。APIキーの漏洩やタイムアウト未処理は、自作ツールが一瞬で使い物にならなくなる典型的な落とし穴です。

APIキー・認証情報の安全な管理方法

ソースコードに直接APIキーを書いた経験はありませんか？ GitHubに誤ってプッシュした場合、悪用されるまでの時間は平均わずか数分といわれています。自作MCPサーバーでは必ず環境変数で管理しましょう。

プロジェクトルートに .env ファイルを作成し、python-dotenv ライブラリで読み込む方法が定番です。.gitignore に .env を追加することを絶対に忘れないでください。

• .env ファイルを .gitignore に追加済みか確認する
• 本番環境ではOSレベルの環境変数か、AWS Secrets Manager などのシークレット管理サービスを使う
• APIキーには最小権限の原則を適用し、不要なスコープは付与しない

タイムアウトとエラーハンドリングの実装

外部APIを呼び出すツールで、タイムアウト処理を省略していませんか？ 応答待ちのまま処理がフリーズすると、Claude側のセッションも巻き込まれて操作不能になることがあります。

タイムアウト値は用途によって異なりますが、一般的なWeb APIへのリクエストなら 5〜30秒 を目安に設定するのが無難です。データベースへのクエリは 10〜60秒 程度が現実的でしょう。

負荷を抑えるキャッシュ設計の考え方

同じ検索クエリやAPIリクエストをClaudeが短時間に繰り返すケースは珍しくありません。都度外部APIを叩くと、レスポンスが遅くなるだけでなく、APIの利用料金が想定の 3〜5倍 に膨らむことも珍しくないといわれています。

シンプルな対策として、Pythonの functools.lru_cache や cachetools を使ったインメモリキャッシュが有効です。TTL（有効期限）を 60〜300秒 程度に設定しておくと、データの鮮度を保ちながら無駄なリクエストを削減できます。

セキュリティとパフォーマンスは、後から追加するより最初から組み込んだほうが格段に楽です。ぜひ開発初期の段階から意識してみてください。

さらに発展させるためのおすすめリソースとツール

セキュリティとパフォーマンスの基本を押さえたら、次はMCPの世界をさらに深く掘り下げてみませんか。公式ドキュメントやコミュニティを活用することで、学習スピードは2〜3倍変わるといっても過言ではありません。

Anthropic公式のMCP仕様書と更新情報の追い方

MCPは2024年末の公開以降、仕様のアップデートが数ヶ月おきに繰り返されています。古い情報をもとに実装すると、非推奨のAPIを使い続けるリスクがあります。

公式ドキュメントはJSON-RPC 2.0の基礎から、ツール・リソース・プロンプトの3つのプリミティブまで体系的にまとめられています。まず仕様書の「Core Architecture」セクションを一読することをおすすめします。

GitHubで参考になるオープンソースMCPサーバー集

「実際にどう実装すればいいのか」で詰まった経験はありませんか。そういうときこそ、先人のコードを読むのが最短ルートです。

コードを読む際は、まずエラーハンドリング部分に着目してください。エッジケースの処理方法を知るだけで、自作サーバーの品質が大きく変わります。

Python力を底上げするおすすめ学習コンテンツ

MCPサーバーを自在に書くには、asyncio・型ヒント・パッケージ管理の3領域を重点的に強化するのが効率的です。

学習リソースは豊富にありますが、実際に手を動かして小さなMCPサーバーを1本完成させることが、最速の上達法です。まずは本記事のコードをベースに、自分の業務や趣味に合わせたツールを作ってみてください。公式コミュニティやGitHubのリソースをフル活用して、カスタムAIツール開発をぜひ楽しんでみてください。