用 Claude Code 从零开发 MCP Server：TypeScript 实战教程（2026）

┌─────────────────────────────────────────────┐
│           MCP 客户端（Host）                 │
│   Claude Code / Cursor / VS Code Copilot    │
├─────────────────────────────────────────────┤
│           MCP 协议层（Protocol）              │
│         JSON-RPC 2.0 + STDIO/HTTP           │
├─────────────────────────────────────────────┤
│           MCP 服务端（Server）                │
│   你开发的工具 / 数据源 / 提示模板            │
└─────────────────────────────────────────────┘

mkdir weather-mcp-server
cd weather-mcp-server
npm init -y

npm install @modelcontextprotocol/server zod
npm install -D typescript @types/node

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

{
  "name": "weather-mcp-server",
  "version": "1.0.0",
  "type": "module",
  "bin": {
    "weather-mcp-server": "./dist/index.js"
  },
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/server";
import { StdioServerTransport } from "@modelcontextprotocol/server";
import * as z from "zod";

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

// 2. 模拟天气数据（实际项目中替换为真实 API 调用）
function getWeatherData(city: string): {
  city: string;
  temperature: number;
  condition: string;
  humidity: number;
} {
  // 模拟数据，实际开发中这里调用天气 API
  const weatherMap: Record<string, { temperature: number; condition: string; humidity: number }> = {
    "北京": { temperature: -2, condition: "晴", humidity: 30 },
    "上海": { temperature: 8, condition: "多云", humidity: 65 },
    "广州": { temperature: 18, condition: "阴", humidity: 75 },
    "深圳": { temperature: 20, condition: "晴", humidity: 70 },
    "杭州": { temperature: 6, condition: "小雨", humidity: 80 },
  };

  const data = weatherMap[city];
  if (!data) {
    return { city, temperature: 15, condition: "未知", humidity: 50 };
  }
  return { city, ...data };
}

// 3. 注册工具：获取天气
server.registerTool(
  "get_weather",
  {
    title: "获取天气",
    description: "查询指定城市的当前天气信息，包括温度、天气状况和湿度",
    inputSchema: z.object({
      city: z.string().describe("城市名称，如：北京、上海、广州"),
    }),
  },
  async ({ city }) => {
    const weather = getWeatherData(city);
    const text = `${weather.city}当前天气：${weather.condition}，温度 ${weather.temperature}°C，湿度 ${weather.humidity}%`;

    return {
      content: [{ type: "text", text }],
    };
  }
);

// 4. 注册工具：对比两个城市天气
server.registerTool(
  "compare_weather",
  {
    title: "对比天气",
    description: "对比两个城市的天气情况",
    inputSchema: z.object({
      city1: z.string().describe("第一个城市"),
      city2: z.string().describe("第二个城市"),
    }),
  },
  async ({ city1, city2 }) => {
    const w1 = getWeatherData(city1);
    const w2 = getWeatherData(city2);
    const diff = w1.temperature - w2.temperature;

    const text = [
      `天气对比：${w1.city} vs ${w2.city}`,
      `---`,
      `${w1.city}：${w1.condition}，${w1.temperature}°C，湿度 ${w1.humidity}%`,
      `${w2.city}：${w2.condition}，${w2.temperature}°C，湿度 ${w2.humidity}%`,
      `---`,
      `温差：${Math.abs(diff)}°C（${diff > 0 ? w1.city + "更暖" : w2.city + "更暖"}）`,
    ].join("\n");

    return {
      content: [{ type: "text", text }],
    };
  }
);

// 5. 启动 STDIO Transport
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("Weather MCP Server 已启动"); // 注意：用 console.error
}

main().catch(console.error);

npx tsc

chmod +x dist/index.js

claude mcp add weather-server node /你的项目绝对路径/dist/index.js

> 帮我查一下北京的天气

> 对比一下上海和广州的天气

claude mcp list

server.registerResource(
  "supported-cities",
  "weather://cities",
  {
    title: "支持的城市列表",
    description: "返回所有支持查询天气的城市",
    mimeType: "application/json",
  },
  async (uri) => ({
    contents: [
      {
        uri: uri.href,
        text: JSON.stringify(["北京", "上海", "广州", "深圳", "杭州"]),
      },
    ],
  })
);

server.registerPrompt(
  "travel-advice",
  {
    title: "出行建议",
    description: "根据目的地天气给出出行穿搭建议",
    argsSchema: z.object({
      destination: z.string().describe("目的地城市"),
    }),
  },
  ({ destination }) => ({
    messages: [
      {
        role: "user" as const,
        content: {
          type: "text" as const,
          text: `请根据${destination}的当前天气，给出出行穿搭和注意事项建议。`,
        },
      },
    ],
  })
);

// 错误 - 会破坏 STDIO 协议
console.log("调试信息");

// 正确 - 走 stderr，不影响通信
console.error("调试信息");

server.registerTool(
  "fetch-data",
  {
    description: "获取数据",
    inputSchema: z.object({ url: z.string() }),
  },
  async ({ url }, ctx) => {
    await ctx.mcpReq.log("info", `正在请求 ${url}`);
    const res = await fetch(url);
    await ctx.mcpReq.log("debug", `响应状态: ${res.status}`);
    const text = await res.text();
    return { content: [{ type: "text", text }] };
  }
);

const server = new McpServer(
  { name: "my-server", version: "1.0.0" },
  { capabilities: { logging: {} } }
);

# 查看已注册的 MCP Server 状态
claude mcp list

# 移除并重新添加（重启 Server）
claude mcp remove weather-server
claude mcp add weather-server node /path/to/dist/index.js

{
  "name": "@your-scope/weather-mcp-server",
  "version": "1.0.0",
  "description": "一个查询天气的 MCP Server",
  "type": "module",
  "bin": {
    "weather-mcp-server": "./dist/index.js"
  },
  "files": ["dist"],
  "keywords": ["mcp", "mcp-server", "weather"],
  "license": "MIT"
}

npm run build
npm publish --access public

claude mcp add weather-server npx @your-scope/weather-mcp-server