用 TypeScript 写第一个 MCP Server

用 TypeScript 写第一个 MCP Server

基础概念

如果你想用 TypeScript 写第一个 MCP Server，当前最稳的路线不是盲目跟 typescript-sdk 仓库 main 分支走，而是先按官方 quickstart 使用 v1 这条稳定线。

原因很简单：

• MCP 官方 quickstart 里 TypeScript 示例仍然使用 @modelcontextprotocol/sdk
• TypeScript SDK 官方 main README 又明确说明：main 是 v2 pre-alpha，生产仍推荐 v1.x

所以今天要写“第一个可用的 TypeScript MCP Server”，最合理的做法是：

1. 按官方 quickstart 用 @modelcontextprotocol/sdk
2. 用 zod 定义输入 schema
3. 先走 stdio 路线接 Claude Desktop
4. 把“我是不是要追 v2”留到后面再处理

核心要素

从 TS 项目到 MCP Server 的链路

为什么 TypeScript 路线一定要记住“先 build”

这一步是很多人第一次写 TS MCP Server 最容易漏掉的地方。

基础用法

第一步：创建项目

官方 quickstart 的 TypeScript 起手式是：

mkdir weather
cd weather
npm init -y
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript
mkdir src
touch src/index.ts

官方 quickstart 对 Node 的要求写的是：

• Node.js 16 或更高

但你如果后面想往 v2 主线迁移，当前 npm registry 上 @modelcontextprotocol/server / client 的 alpha 包已经要求 Node >=20。所以从长期角度看，本机环境直接准备 Node 20+ 会更稳。

第二步：补 package.json

官方 quickstart 还要求你把 package.json 至少补成这样：

{
  "type": "module",
  "bin": {
    "weather": "./build/index.js"
  },
  "scripts": {
    "build": "tsc && chmod 755 build/index.js"
  },
  "files": [
    "build"
  ]
}

这里最关键的不是 bin，而是：

• type: "module"
• 有一个稳定的 build 输出目录

第三步：写 tsconfig.json

官方 quickstart 示例是：

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

第四步：写一个最小 Server

下面这段结构，基本就是官方 quickstart 的最小核心：

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: "demo",
  version: "1.0.0",
  capabilities: {
    resources: {},
    tools: {},
  },
});

server.tool(
  "add",
  "Add two numbers",
  {
    a: z.number(),
    b: z.number(),
  },
  async ({ a, b }) => {
    return {
      content: [
        {
          type: "text",
          text: String(a + b),
        },
      ],
    };
  },
);

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

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

这里面最重要的几个点：

• McpServer 是服务端主体
• server.tool(...) 注册工具
• zod 负责参数 schema
• StdioServerTransport 负责本地 stdio 传输

第五步：编译

这一步官方 quickstart 强调得非常明确：

npm run build

如果你没做这一步，Claude Desktop 后面根本没有现成的 build/index.js 可跑。

第六步：接入 Claude Desktop

官方 quickstart 给出的配置是：

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": [
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js"
      ]
    }
  }
}

这里的关键不是名字，而是：

• 用 node
• 跑的是 绝对路径
• 跑的是编译后的 build/index.js

第七步：什么时候再看 v2

如果你这时已经把第一版跑通了，才值得回去看 TypeScript SDK 的 v2 主线。因为那时你已经有了：

• MCP Server 结构感
• tool schema 感
• transport 感
• 客户端配置感

再看拆包后的 @modelcontextprotocol/server / client，理解成本会低很多。

同类工具对比

如果目标是“用 TS 写第一个 MCP Server”，几种常见路径可以这样看：

核心区别：

• TS v1 quickstart：适合立刻上手、立刻做出能跑的东西。
• TS v2：适合进一步演进和预研，不是第一步。
• Python FastMCP：更偏“高层开发体验优先”。

常见误区

优劣势分析

思考题

参考资料

1. MCP 官方 quickstart：Server Developer Guide（Node 部分）：https://modelcontextprotocol.io/quickstart/server（查询日期 2026-04-11）
2. MCP TypeScript SDK v1.x README：https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/README.md（查询日期 2026-04-11）
3. MCP TypeScript SDK v1.x server 文档：https://github.com/modelcontextprotocol/typescript-sdk/blob/v1.x/docs/server.md（查询日期 2026-04-11）
4. MCP TypeScript SDK 概览：https://modelcontextprotocol.io（查询日期 2026-04-11）