0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

MCPサーバーに関して⑤:自作入門:最小のMCPサーバーを作る

0
Posted at

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(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がここからツールの説明文を作る。
  • 副作用:プログラムの実行によって、ファイルやデータベースなど外部の状態が変わること。読み取りだけの処理には副作用がない。
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?