MCPサーバーに関して⑤:自作入門:最小のMCPサーバーを作る
前回(④)までは、公開されているMCPサーバーをクライアントに接続する「使う側」の話でした。今回からは「作る側」に回ります。
この記事では、公式SDKを使ってツール1個だけの最小サーバーを作り、ローカルで動かすところまでを解説します。コードは短く、仕組みは3つの部品だけです。
この記事で分かること
- 最小のMCPサーバーが持つ3つの部品
- TypeScriptで最小サーバーを作る手順
- Pythonで同じものを書くときの違い
- 動かす前の確認方法と、つまずきやすい注意点
最小サーバーの3つの部品
MCPサーバーは、どんなに大きくても次の3つでできています。
| 部品 | 役割 |
|---|---|
| サーバーオブジェクト | 名前とバージョンを持ち、ツールを束ねる |
| ツールの登録 | 「何ができるか」と「どう動くか」を定義する |
| トランスポートへの接続 | クライアントとメッセージをやり取りする経路につなぐ |
ローカルで動かす最小構成では、トランスポートは stdio を使います。クライアントがサーバーのプロセスを起動し、標準入出力でJSON-RPCのメッセージを交換する方式です(②で解説した通りです)。
手順1:プロジェクトを用意する
TypeScriptの公式SDKは、現在 v2 が安定版の系統です。パッケージ名は @modelcontextprotocol/server で、2026-07-28版のMCP仕様に対応しています。Node.jsは 20以上 を使います。
mkdir my-first-mcp-server && cd my-first-mcp-server
npm init -y
npm pkg set type=module
npm install @modelcontextprotocol/server zod
npm install -D tsx
zod はツールの入力の形を宣言するためのライブラリです。SDKはこの宣言から、クライアントへ渡す入力スキーマ(JSON Schema)を自動で作ります。tsx はTypeScriptを直接実行するためのツールで、ビルドの手順が不要になります。type=module は、SDKがESモジュールのみで提供されているため必要です。
手順2:ツール1個のサーバーを書く
作るのは、渡された文字列の文字数を数える count_chars というツール1個だけのサーバーです。ファイルは src/index.ts に置きます。
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';
// サーバーを作る関数(ファクトリ)。接続ごとに新しい実体を作る
function createServer(): McpServer {
// 1. サーバーオブジェクトを作る
const server = new McpServer({ name: 'count-server', version: '1.0.0' });
// 2. ツールを登録する
server.registerTool(
'count_chars',
{
description: '渡された文字列の文字数を数えて返す',
inputSchema: z.object({ text: z.string() }),
},
async ({ text }) => ({
content: [{ type: 'text', text: `文字数は ${text.length} 文字です。` }],
})
);
return server;
}
// 3. ファクトリを渡してstdioで待ち受ける
void serveStdio(createServer);
ポイントは3つです。
-
registerToolの第2引数は、ツール名の次に「説明」と「入力スキーマ」を渡します。説明文はLLMが「このツールを使うべきか」を判断する材料になるので、何をするツールかを具体的に書きます。 -
戻り値は
contentの配列です。テキストを返す場合は{ type: 'text', text: '...' }という形にします。 -
起動は
serveStdio(createServer)です。serveStdioはクライアントごとにプロトコルの版を交渉するので、新しい版(2026-07-28)のクライアントにも古い版のクライアントにも対応できます。server.connect(new StdioServerTransport())と手書きで配線する方法もありますが、そちらは古い版のクライアントにしか対応しないため、今はserveStdioを使うのが推奨です。
実行は tsx で直接行います。ビルドの手順は不要です。
npx tsx src/index.ts
何も表示されなければ正常です。stdioサーバーは、クライアントからのメッセージを待っている状態です。止めるときは Ctrl+C です。
手順3:Pythonで書く場合
Pythonの公式SDK(パッケージ名 mcp、2.0.0以上)でも、同じ考え方で書けます。こちらは 型ヒントとdocstringから入力スキーマが自動生成される のが特徴で、スキーマを自分で書く必要がありません。
uv add "mcp[cli]"
from mcp.server import MCPServer
mcp = MCPServer("count-server")
@mcp.tool()
def square(n: int) -> int:
"""整数を2乗して返す。"""
return n * n
TypeScript版との対応関係はこうなります。
| 役割 | TypeScript | Python |
|---|---|---|
| サーバーを作る | new McpServer({...}) |
MCPServer("count-server") |
| ツールを登録する | server.registerTool(...) |
@mcp.tool() デコレータ |
| 入力の形を決める | Zodの inputSchema
|
引数の型ヒント |
| ツールの説明 | description |
関数のdocstring |
どちらを選ぶかは、チームが慣れている言語で決めてかまいません。プロトコルは同じなので、TypeScript製のサーバーをPython製のクライアントから呼ぶこともできます。
手順4:動くことを確かめる
いきなりクライアントに接続する前に、公式のテスト用ツール MCP Inspector で確認します。
npx @modelcontextprotocol/inspector npx tsx src/index.ts
Inspectorが起動したら、count_chars がツール一覧に出ること、実際に文字列を渡して文字数が返ることを確かめます。Pythonの場合は uv run mcp dev server.py で同じように確認できます。
なお、Inspectorは既定では古い版(2025年時代)の手順で接続します。新しい版(2026-07-28)のクライアントへの対応まで確認したい場合は、Inspectorの起動時に --protocol-era modern を付けて実行します。
動くことが確認できたら、④で紹介した方法でクライアントの設定ファイルにサーバーを登録します。Claude Desktopなら設定ファイルの mcpServers に、起動コマンド(TypeScriptなら node でビルド済みのファイルを指定)を書いて再起動するだけです。
つまずきやすい注意点
最小サーバーで失敗する原因は、たいてい次の3つです。
stdoutに何も書かない
stdioでは、標準出力がそのままプロトコルの通信路です。console.log を1行でも書くと、JSON-RPCのメッセージが壊れてサーバーが動かなくなります。ログを出したいときは console.error を使いましょう(標準エラー出力は通信路と別です)。Pythonでも同じで、print() は使いません。
ツールの説明を雑に書かない
LLMはツールの description を読んで、使うかどうかを決めます。「便利なツールです」のような説明では、呼ばれなかったり、誤って呼ばれたりします。「何を受け取り、何を返すか」を1文で具体的に書くのがコツです。
最初から機能を詰め込まない
ツールは1個ずつ増やすのが基本です。まず count_chars のような副作用のない(外部の状態を変えない)ツールで、登録から接続までの流れを通して動かします。動く形ができてから、ファイル操作や外部API呼び出しのような実用的なツールを追加していきましょう。
まとめ
- 最小のMCPサーバーは「サーバーオブジェクト」「ツールの登録」「トランスポートへの接続」の3部品だけ
- TypeScriptは
@modelcontextprotocol/serverのMcpServerとregisterTool、起動はserveStdio、入力スキーマにはZodを使う - Pythonは
mcpパッケージのMCPServerと@mcp.tool()、型ヒントとdocstringがスキーマになる - stdioでは標準出力に何も書かない(ログは標準エラー出力へ)
- 動かす前にMCP Inspectorでツール一覧と呼び出しを確認する
次回(⑥)は、ツールの実装をもう一歩進めて、スキーマの定義、引数のバリデーション、エラー処理など、実装でつまずきやすい点を解説します。
関連記事
- MCPサーバーに関して④:使う側から始める:既存サーバーの導入と接続
- MCPサーバーに関して③:サーバーが提供する3つの機能
- MCPサーバーに関して②:通信の仕組み
- MCPサーバーに関して①:全体像と基本概念
参考リンク
用語集
- MCP(Model Context Protocol):LLMアプリケーションと外部のデータやツールを、共通の決まりでつなぐためのプロトコル(通信の約束事)。
- SDK(Software Development Kit):特定の技術を使うための公式のライブラリやツールの詰め合わせ。ここではMCPサーバーを作るための公式ライブラリ。
- stdio:標準入出力(standard input / output)の略。プロセス同士が、キーボード入力や画面出力と同じ仕組みでメッセージをやり取りする方式。
- トランスポート:クライアントとサーバーの間でメッセージを運ぶ経路。stdioとStreamable HTTPがある。
- JSON-RPC:JSON形式で「メソッド名」と「引数」を送り、「結果」を受け取る、リモート呼び出しの仕組み。MCPのメッセージ交換の土台。
- Zod:TypeScriptでデータの形(スキーマ)を宣言し、検証するためのライブラリ。
- MCP Inspector:MCPサーバーの動作を試すための公式のテスト用ツール。ツール一覧の表示や呼び出しができる。
-
デコレータ:Pythonで関数やクラスの定義の上に付けて、その振る舞いを拡張する記法。
@mcp.tool()は関数をMCPのツールとして登録する。 - 型ヒント:Pythonで引数や戻り値の型を注釈として書くこと。SDKがここから入力スキーマを作る。
- docstring:Pythonの関数やクラスの中に書く説明文。SDKがここからツールの説明文を作る。
- 副作用:プログラムの実行によって、ファイルやデータベースなど外部の状態が変わること。読み取りだけの処理には副作用がない。