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按鈕可以選擇資源或Prompt，則表示成功。

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服務器。