Local MCP Server Tutorial

🚀 ローカルMCPサーバーの作成チュートリアル

このチュートリアルでは、ローカルMCPサーバーを作成する方法を案内します。

🚀 クイックスタート

✨ 主な機能

• ローカルでMCPサーバーを構築することができます。
• 各種リソースやツールを定義し、利用することができます。
• デバッグやパッケージの公開、公開したサーバーの実行が可能です。

📦 インストール

準備物

• Node.js（v22の使用を推奨）
• Claude Desktopまたはその他のMCPクライアント

💻 使用例

基本的な使用法

1. プロジェクトの作成

npx giget@latest gh:7nohe/local-mcp-server-tutorial my-mcp-server
cd my-mcp-server
npm install
git init
git branch -M main
git add .
git commit -m "Initial commit"

2. TypeScriptコードのビルドと実行

以下のsrc/index.tsの内容をビルドして実行します。

#!/usr/bin/env node
async function main() {
  console.error("Hello, world!");
}

main().catch((error) => {
  console.error("Fatal error in main():", error);
  process.exit(1);
});

npm run build
./dist/index.js
# 出力: Hello, world!

⚠️ 重要提示 package.jsonのbin属性を設定することで、node_modules/.bin/以下にシンボリックリンクが作成され、./dist/index.jsを実行できるようになります。

3. 必要なライブラリのインストール

npm install @modelcontextprotocol/sdk zod

4. MCPサーバーの実装

#!/usr/bin/env node
import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// MCPサーバーインスタンスの作成
const server = new McpServer({
  name: "my-mcp-server",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

async function main() {
  const transport = new StdioServerTransport();
  // リソース

  // “Hello, world!”を返すリソース定義
  server.resource(
    "Greeting",
    "greeting://hello",
    (uri, { }) => {
      console.log(uri)
      return {
        contents: [
          {
            uri: uri.href,
            text: "Hello, world!",
          }
        ]
      }
    })

  // ResourceTemplateを使用した動的リソースの実装
  server.resource(
    "Greeting with name",
    new ResourceTemplate("greeting://hello/:name"),
    (uri, params) => {
      return {
        contents: [
          {
            uri: uri.href,
            text: `Hello, ${params.name}!`,
          }
        ]
      }
    })
  // ツール

  // 電卓ツールの定義
  server.tool("calculator", {
    add: (a: number, b: number) => a + b,
    subtract: (a: number, b: number) => a - b,
    multiply: (a: number, b: number) => a * b,
    divide: (a: number, b: number) => a / b,
  });
}

// サーバーの起動
main().catch((error) => {
  console.error("Server failed to start:", error);
});

5. デバッグ

Inspectorを使用してデバッグします。

npx @modelcontextprotocol/inspector ./dist/index.js

ブラウザでhttp://127.0.0.1:6274を開くと、定義したリソースやツールのレスポンスを確認できます。

⚠️ 重要提示 作業を効率化するために、npm run watchを実行すると、コードが変更されるたびに自動的に再ビルドされます。

次に、Claude Desktopで検証します。Settings -> Developer -> Edit Configからclaude_desktop_config.jsonを開き、以下のように設定します。

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "/<プロジェクトの絶対パス>/my-mcp-server/dist/index.js"
    }
  }
}

保存してClaude Desktopを再起動します。ツールボタンに一覧が表示され、Attach from MCPボタンからリソースまたはプロンプトを選択できれば成功です。

6. パッケージの公開

npm login
npm publish

⚠️ 重要提示 package.jsonのnameを@your-name/my-mcp-serverに設定することで、自分のパッケージを明確に識別できます。

⚠️ 注意事項 npmパッケージは一度公開すると削除が難しいため、慎重に操作してください。

💡 使用建议

• package.jsonのscripts.prepublishOnlyをビルドコマンドに設定することで、npm publish時に自動的にビルドされます。
• package.jsonのbin属性を設定することで、CLIとして実行できます。

"bin": "./dist/index.js"

• package.jsonのfiles属性を設定することで、公開するファイルを指定できます。

"files": [
  "dist"
]

7. 公開したMCPサーバーの実行

Claude Desktopで以下のように設定します。

"my-mcp-server": {
  "command": "npx",
  "args": [
    "@your-name/my-mcp-server@latest"
  ]
}

これにより、コマンドで公開したMCPサーバーを実行できます。