minimal-mcp-server

MCP（Model Context Protocol）を学ぶための最小構成のサーバー実装です。 Claude Desktop と接続して、チャットからツールを呼び出すことができます。

提供ツール

ツール名	説明	引数
echo	入力されたメッセージをそのまま返す	message (string)
get-current-time	サーバーの現在日時を返す	なし
search-wikipedia	日本語Wikipediaで記事の要約を検索する（外部API連携）	query (string)

セットアップ

必要環境

• Node.js v18 以上（fetch API を使用するため）
• npm

インストール

git clone <repository-url>
cd minimal-mcp-server
npm install

ビルド

npm run build

src/index.ts が build/index.js にコンパイルされます。

動作確認

npm start

stdio で待ち受け状態になれば成功です（Ctrl+C で終了）。

Claude Desktop との接続

1. 設定ファイルを編集

macOS の場合:

~/Library/Application Support/Claude/claude_desktop_config.json

以下を mcpServers に追加します:

{
  "mcpServers": {
    "minimal-mcp-server": {
      "command": "node",
      "args": ["/path/to/minimal-mcp-server/build/index.js"]
    }
  }
}

/path/to/ は実際のパスに置き換えてください。

2. Claude Desktop を再起動

再起動後、チャット入力欄のハンマーアイコンをクリックすると、登録されたツールが一覧に表示されます。

3. ログの確認

MCPサーバーのログは以下に出力されます:

tail -f ~/Library/Logs/Claude/mcp-server-minimal-mcp-server.log

stdio トランスポートでは console.log（stdout）は MCP 通信と干渉するため、ログには必ず console.error（stderr）を使用してください。

使い方（Claude Desktop での質問例）

ツールは自然言語で質問するだけで、Claude が自動的に適切なツールを選んで実行します。

echo

「Hello World」とエコーして

get-current-time

今何時？

search-wikipedia

東京タワーについて教えて
富士山のWikipedia情報を調べて

開発ガイド

プロジェクト構成

minimal-mcp-server/
├── src/
│   └── index.ts          # サーバー本体（ツール定義含む）
├── build/                 # コンパイル出力（git管理外）
├── package.json
└── tsconfig.json

ツールの追加方法

src/index.ts に server.registerTool() を追加します:

server.registerTool(
  "tool-name",             // ツール名（ケバブケース推奨）
  {
    description: "ツールの説明（Claudeがツール選択の判断に使う）",
    inputSchema: {         // 引数定義（Zodスキーマ）省略可
      param1: z.string().describe("引数の説明"),
      param2: z.number().describe("引数の説明"),
    },
  },
  async ({ param1, param2 }) => {
    // ツールの処理
    return {
      content: [
        { type: "text", text: "結果のテキスト" },
      ],
    };
  },
);

ポイント

• description は重要です。Claude はこの説明文を見てどのツールを使うか判断します。具体的に書くほど正確に呼び出されます
• inputSchema は Zod で定義し、自動的に JSON Schema に変換されてクライアントに公開されます
• 引数なしのツールは inputSchema を省略できます
• 戻り値は content 配列で、type: "text" のオブジェクトを返します

外部 API 連携の例（search-wikipedia）

server.registerTool(
  "search-wikipedia",
  {
    description: "日本語Wikipediaでキーワードを検索し、記事の要約を返すツール",
    inputSchema: {
      query: z.string().describe("検索キーワード（例: 東京タワー）"),
    },
  },
  async ({ query }) => {
    const url = `https://ja.wikipedia.org/api/rest_v1/page/summary/${encodeURIComponent(query)}`;
    const res = await fetch(url);
    if (!res.ok) {
      return {
        content: [
          { type: "text", text: `「${query}」に該当する記事が見つかりませんでした。` },
        ],
      };
    }
    const data = await res.json();
    return {
      content: [
        {
          type: "text",
          text: `【${data.title}】\n${data.extract}\n\nURL: ${data.content_urls?.desktop?.page ?? "N/A"}`,
        },
      ],
    };
  },
);

技術スタック

技術	用途
MCP SDK (@modelcontextprotocol/sdk)	MCP サーバーフレームワーク
Zod	引数のスキーマ定義・バリデーション
TypeScript	型安全な開発
StdioServerTransport	Claude Desktop との通信（stdin/stdout）

トランスポートについて

このサーバーは stdio トランスポート を使用しています。Claude Desktop はこの方式でMCPサーバーと通信します。

Claude Desktop → stdin → StdioServerTransport → McpServer → ツール実行
                                                                 ↓
Claude Desktop ← stdout ← StdioServerTransport ← McpServer ← 結果返却

Web アプリとして公開する場合は StreamableHTTPServerTransport を使用します（別途実装が必要）。