MCPカスタムサーバーの作り方 — TypeScript・Python初心者ガイド

ClaudeのようなAIアシスタントに、自分が大切に整理したメモや、普段よく使うコンピューター上のスクリプトを直接接続できたら便利だと思いませんか？最近のAIエコシステムで最も注目されている「モデル・コンテキスト・プロトコル（MCP）」を活用すれば、高度な専門知識がなくても、自分専用のカスタマイズAIアシスタントを簡単に作ることができます。PC内のローカルデータとAIをシームレスにつなぐカスタムサーバーの構築方法を、今すぐ楽しく学んでみましょう！

なぜ自分専用のカスタムサーバーが必要なのか？

既にインターネット上で公開されている様々なMCPサーバーを利用するのも素晴らしい第一歩です。リアルタイム検索をサポートするBrave Searchサーバーや、PC内のフォルダを読み込むツールを接続するだけでも、Claudeの活用範囲は劇的に広がります。

しかし、本当の面白さは「自分だけのデータ」を扱い始めた時に生まれます。自分で書き溜めたローカルの日記、社内専用のプライベートデータベース、あるいは日常的に実行しているPythonの自動化スクリプトをClaudeに接続した瞬間、世界で一つだけの超パーソナライズされたアシスタントが誕生するのです。

サーバーを作ることは決して難しいことではありません。複雑なネットワークバックエンドの知識を深く知る必要もありません。わずか数行のコードがあれば、ローカル環境とClaudeを安全につなぐ堅牢なパイプラインがすぐに完成します。

TypeScriptでの実装：より簡潔になったv2 SDK

まず最初に紹介するのは、ウェブエコシステムの代表格であるTypeScriptです。

最近公開されたTypeScript SDK v2は、既存の複雑な設定手順を大幅に簡略化し、より直感的に生まれ変わりました。これからは@modelcontextprotocol/server パッケージが提供するMcpServer オブジェクトとserveStdio ヘルパーさえあれば、わずか数行でカスタムサーバーを実行できます。

TypeScript SDK v2に基づいた、最も基本的な天気情報提供サーバーの例を見てみましょう。

// TypeScript SDK v2 기준
import { McpServer } from "@modelcontextprotocol/server";
import { serveStdio } from "@modelcontextprotocol/server/stdio";
import { z } from "zod";

const server = new McpServer({
  name: "my-weather-server",
  version: "1.0.0"
});

// 도구 등록하기
server.registerTool(
  "get-weather",
  {
    description: "특정 지역의 날씨 정보를 가져옵니다.",
    inputSchema: z.object({
      location: z.string().describe("날씨를 조회할 도시 이름 (예: 서울, 부산)")
    })
  },
  async ({ location }) => {
    return {
      content: [{ type: "text", text: `${location}의 현재 날씨는 맑음입니다.` }]
    };
  }
);

// stdio 방식으로 서버 실행
serveStdio(() => server);

このコードを実行する際、初心者が最も頻繁に遭遇する致命的な罠があります。それは「標準出力ノイズ」の問題です。

Claude Desktopのようなプログラムは、作成したMCPサーバーと「標準入出力」という仮想的な接続線を通じて通信します。この接続線は、決まった規格のJSON-RPCデータだけが行き来できる、クリーンな専用電話線のようなものです。

ところが、デバッグのために何気なくコードの途中にconsole.logを記述するとどうなるでしょうか？これは専用の電話線に向かって突然大声で叫ぶようなものです。Claudeが割り込んできた正体不明のテキストによって通信エラーを起こし、最終的に接続が切断されてしまいます。

そのため、MCPサーバー内で動作を確認したい場合は、必ずconsole.errorを使用しなければなりません。このコマンドは「標準エラー」という別の予備経路へメッセージを出力するため、専用の電話線にノイズを発生させることなく、安全にログを監視することができます。

Pythonでの実装：デコレータ1行の魔法

Pythonをメインツールとして使っているなら、新しいPython SDK v2の「FastMCP」インターフェースを使えば、さらに簡単かつシンプルにカスタムサーバーを作成できます。複雑な設定コードを書く必要はなく、普段使っている関数にデコレータを1行追加するだけで準備は完了です。

Pythonの標準機能である型ヒントと関数の説明文をしっかり書いておけば、@mcp.tool()デコレータがそれを自動的に読み取り、Claudeが理解できるJSONスキーマ形式に変換してくれます。最もシンプルなサンプルコードで、どのように実装するのか見ていきましょう。

python

# Python SDK v2 (FastMCP) 기준 예시
from mcp.server.fastmcp import FastMCP

# FastMCP 서버 인스턴스 생성
mcp = FastMCP("My Custom Server")

@mcp.tool()
def calculate_shipping(weight: float, zone: str) -> str:
    """배송 요금을 계산하는 도구입니다."""
    # print()는 통신을 방해하므로 사용하지 않고, 로깅 라이브러리를 사용해 출력합니다.
    price = weight * (1.5 if zone == "US" else 2.5)
    return f"배송료: ${price:.2f}"

ここで一つ、覚えておくべき重要な秘密があります。コード内で習慣的に使いがちなprint()関数を絶対に使ってはいけないという点です。AIとサーバーがデータをやり取りする専用経路がprint()の出力によって汚染されると、通信が遮断されてしまうからです。ログやデバッグメッセージを残したい場合は、Python標準ライブラリのロギングシステムを使用して標準エラーに出力するのが安全です。

開発や登録のプロセスも、かつてないほど便利になりました。ターミナルでmcp dev server.pyコマンドを実行すると、コードを修正するたびに自動でリアルタイムに反映され、6274ポートで開くウェブダッシュボード（MCP Inspector UI）で即座に連携状態をテストできます。開発が終わったらmcp install server.pyコマンドを入力すれば、複雑なパス指定なしで、一度にClaude Desktopアプリへサーバーを登録できます。

Claude Desktopに自作サーバーを連携する

素敵なカスタムサーバーコードが完成したら、次はPCで動作しているClaude Desktopに接続する番です。設定手順は思ったよりもずっと簡単です。Claude Desktopの環境設定ファイルであるclaude_desktop_config.jsonに、サーバーの実行方法を記述するだけです。

まず、この設定ファイルを探して開く必要があります。OSに応じて以下のパスを確認してください。

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

もし該当フォルダにファイルがなければ、新しくテキストエディタを開いて直接作成しても構いません。ファイルを開いたら、以下のように先ほど作成したサーバーを登録します。この際、スクリプトファイルのパスは必ず絶対パスで記述しないとエラーになります。

json

{
  "mcpServers": {
    "my-python-server": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp",
        "python",
        "/Users/username/mcp-server/server.py"
      ]
    }
  }
}

上記の設定は、Pythonサーバーを最も迅速かつ安全に実行するuv run方式を活用した例です。複雑な仮想環境を作成したりパッケージを事前インストールしたりすることなく、実行時に必要なパッケージを自動で取得・起動してくれる簡潔な手法です。もしTypeScriptサーバーを登録したい場合はnpx -y tsx /절대경로/server.tsのようにコマンドを構成すれば、ビルド手順なしですぐに連携可能です。

設定が終わったら、Claude Desktopアプリを一度完全に終了してから再起動してください。対話画面の右下にプラグインのようなコンセントアイコンが有効になっていれば、全ての準備は完了です。

エージェント時代を自分だけの武器で切り拓く

今やAIは単に指示されたことをこなすだけのアシスタントを超え、私たちの働き方を教え込むことができるパートナーとなりました。日頃よく使うTypeScriptやPythonのコードがあるなら、迷わず自分だけの最初のMCPサーバーを自作してみてください。自分のワークフローにぴったりフィットしたツールが増えるたび、自分だけのカスタムエージェントと一緒に働く楽しさを実感できるはずです！