如何用 TypeScript 构建 MCP 服务器（分步教程）

学习如何使用官方 @modelcontextprotocol/sdk 用 TypeScript 构建 MCP 服务器，用 Zod 验证输入，并配置到 Claude Code 和 Cursor。

前置条件

Node.js 16+（推荐 18+）
npm 或 pnpm
基本 TypeScript 知识

步骤 1 — 搭建项目

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @modelcontextprotocol/sdk zod@3
npm install -D @types/node typescript
mkdir src && touch src/index.ts

SDK 当前版本 @modelcontextprotocol/sdk v1.29.0。

步骤 2 — 创建基础服务器

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

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

server.registerTool(
  "add",
  {
    description: "Add two numbers",
    inputSchema: {
      a: z.number().describe("First number"),
      b: z.number().describe("Second number"),
    },
  },
  async ({ a, b }) => ({
    content: [{ type: "text", text: String(a + b) }],
  }),
);

async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error("MCP Server running");
}

main().catch(console.error);

步骤 3 — 结构化输出

server.registerTool(
  "calculate-bmi",
  {
    description: "Calculate BMI",
    inputSchema: z.object({
      weightKg: z.number(),
      heightM: z.number(),
    }),
    outputSchema: z.object({
      bmi: z.number(),
      category: z.string(),
    }),
  },
  async ({ weightKg, heightM }) => {
    const bmi = weightKg / (heightM * heightM);
    const output = { bmi: Math.round(bmi * 10) / 10, category: bmi < 18.5 ? "偏轻" : bmi < 25 ? "正常" : "偏重" };
    return { content: [{ type: "text", text: JSON.stringify(output) }], structuredContent: output };
  },
);

步骤 4 — 测试

npm run build
npx @modelcontextprotocol/inspector node build/index.js

步骤 5 — 配置

Claude Code：claude mcp add --transport stdio my-server -- node /path/to/build/index.js

Cursor（.cursor/mcp.json）：

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

重要：stdio 模式下不要用 console.log()，用 console.error() 打日志。

FAQ

Q: 用哪个 SDK 版本？ A: v1.29.0 稳定版。v2 SDK 还在 pre-alpha，生产环境用 v1.x。