5 分钟构建你的第一个 MCP Server：Node.js 快速入门教程

mkdir my-first-mcp-server
cd my-first-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D typescript @types/node

npx tsc --init

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"]
}

{
  "type": "module",
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";

// 1. 创建 Server 实例
const server = new McpServer({
  name: "my-first-mcp-server",
  version: "1.0.0",
});

// 2. 注册一个 Tool
server.tool(
  "get-weather",
  "获取指定城市的当前天气信息",
  {
    city: z.string().describe("城市名称，例如 Beijing、Tokyo、New York"),
  },
  async ({ city }) => {
    // 这里用模拟数据演示，实际项目中替换为真实 API 调用
    const weatherData: Record<string, { temp: number; condition: string }> = {
      Beijing: { temp: 22, condition: "晴" },
      Tokyo: { temp: 18, condition: "多云" },
      "New York": { temp: 15, condition: "小雨" },
    };

    const weather = weatherData[city];

    if (!weather) {
      return {
        content: [
          {
            type: "text" as const,
            text: `未找到城市 "${city}" 的天气数据。支持的城市：${Object.keys(weatherData).join("、")}`,
          },
        ],
      };
    }

    return {
      content: [
        {
          type: "text" as const,
          text: `${city} 当前天气：${weather.condition}，温度 ${weather.temp}°C`,
        },
      ],
    };
  }
);

// 3. 启动 Server
const transport = new StdioServerTransport();
await server.connect(transport);

npx tsc

node dist/index.js

npx @modelcontextprotocol/inspector node dist/index.js

{
  "content": [
    {
      "type": "text",
      "text": "Beijing 当前天气：晴，温度 22°C"
    }
  ]
}

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

%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-first-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/my-first-mcp-server/dist/index.js"]
    }
  }
}

server.tool(
  "calculate-bmi",
  "根据身高和体重计算 BMI 指数",
  {
    height: z.number().describe("身高，单位厘米"),
    weight: z.number().describe("体重，单位千克"),
  },
  async ({ height, weight }) => {
    const heightInMeters = height / 100;
    const bmi = weight / (heightInMeters * heightInMeters);
    const bmiFixed = bmi.toFixed(1);

    let category: string;
    if (bmi < 18.5) category = "偏瘦";
    else if (bmi < 24) category = "正常";
    else if (bmi < 28) category = "偏胖";
    else category = "肥胖";

    return {
      content: [
        {
          type: "text" as const,
          text: `BMI: ${bmiFixed}（${category}）\n身高: ${height}cm / 体重: ${weight}kg`,
        },
      ],
    };
  }
);

server.tool(
  "generate-uuid",
  "生成一个或多个 UUID v4",
  {
    count: z.number().min(1).max(50).default(1).describe("生成数量，1-50"),
  },
  async ({ count }) => {
    const uuids = Array.from({ length: count }, () => crypto.randomUUID());

    return {
      content: [
        {
          type: "text" as const,
          text: uuids.join("\n"),
        },
      ],
    };
  }
);

server.resource(
  "server-info",
  "info://server",
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        mimeType: "application/json",
        text: JSON.stringify({
          name: "my-first-mcp-server",
          version: "1.0.0",
          tools: ["get-weather", "calculate-bmi", "generate-uuid"],
          uptime: process.uptime(),
        }),
      },
    ],
  })
);

server.prompt(
  "weather-report",
  { city: z.string() },
  ({ city }) => ({
    messages: [
      {
        role: "user",
        content: {
          type: "text",
          text: `请查询 ${city} 的天气，并用简洁的方式报告当前温度和天气状况。`,
        },
      },
    ],
  })
);

my-first-mcp-server/
  ├── src/
  │   └── index.ts          # Server 主文件
  ├── dist/
  │   └── index.js           # 编译产物
  ├── package.json
  ├── tsconfig.json
  └── node_modules/

src/
  ├── index.ts               # Server 入口，注册所有 Tool
  ├── tools/
  │   ├── weather.ts         # 天气相关工具
  │   ├── calculator.ts      # 计算类工具
  │   └── uuid.ts            # UUID 生成
  └── utils/
      └── validators.ts      # 通用校验逻辑

# macOS
tail -f ~/Library/Logs/Claude/mcp*.log

# Windows
# %APPDATA%\Claude\Logs\mcp*.log