MCP TypeScript SDK

[!IMPORTANT]
这是 main 分支——SDK 的 v2 版本（Beta 阶段），包名为 @modelcontextprotocol/server 和 @modelcontextprotocol/client，实现了 2026-07-28 MCP 规范。

有反馈？请提交 v2 问题 ——这目前是对 SDK 最有帮助的贡献。v2 文档 从十分钟的服务器教程开始。

我们预计在 2026 年 7 月 28 日与 2026-07-28 规范的完整发布同时推出稳定版本。在此之前，v1.x 仍是生产环境支持的版本，在 v2 发布后至少 6 个月内持续接收错误修复和安全更新。v1 文档：ts.sdk.modelcontextprotocol.io · v2：/v2/。

[!WARNING]
在完成 2026-07-28 规范 的实现期间，每位新贡献者限提交 1 个拉取请求。

提交 Issue 是目前最有价值的反馈方式——v2 稳定后我们将重新接纳拉取请求。

概述

Model Context Protocol (MCP) 允许应用程序以标准化的方式为 LLM 提供上下文，将提供上下文的关注点与实际的 LLM 交互分离开来。

本仓库包含 MCP 规范的 TypeScript SDK 实现。它支持运行在 Node.js、Bun 和 Deno 上，并提供：

• MCP 服务器库（工具/资源/提示、可流式 HTTP、stdio、认证辅助工具）
• MCP 客户端库（传输层、高层辅助工具、OAuth 辅助工具）
• 针对特定运行时/框架的可选中间件包（Express、Hono、Node.js HTTP）
• 可运行的示例（位于 examples/）

包

本单仓库发布拆分包：

• @modelcontextprotocol/server：构建 MCP 服务器
• @modelcontextprotocol/client：构建 MCP 客户端

工具和提示模式使用 Standard Schema——可选用 Zod v4、Valibot、ArkType 或任何兼容的库。

中间件包（可选）

SDK 还在 packages/middleware/ 下发布了小型的“中间件”包，帮助您将 MCP 接入特定的运行时或 Web 框架。

这些包是故意精简的适配器，不应引入新的 MCP 功能或业务逻辑。详见 packages/middleware/README.md。

• @modelcontextprotocol/node：Node.js 可流式 HTTP 传输封装，适用于 IncomingMessage/ServerResponse
• @modelcontextprotocol/express：Express 辅助工具（应用默认值 + Host 头验证）
• @modelcontextprotocol/hono：Hono 辅助工具（应用默认值 + JSON 体解析钩子 + Host 头验证）

安装

服务器

npm install @modelcontextprotocol/server
# 或
bun add @modelcontextprotocol/server
# 或
deno add npm:@modelcontextprotocol/server

客户端

npm install @modelcontextprotocol/client
# 或
bun add @modelcontextprotocol/client
# 或
deno add npm:@modelcontextprotocol/client

可选的中间件包

SDK 还发布了可选的“中间件”包，帮助您将 MCP 接入特定的运行时或 Web 框架（例如 Express、Hono 或 Node.js http）。

这些包是故意精简的适配器，不应引入额外的 MCP 功能或业务逻辑。详见 packages/middleware/README.md。

# Node.js HTTP (IncomingMessage/ServerResponse) 可流式 HTTP 传输：
npm install @modelcontextprotocol/node

# Express 集成：
npm install @modelcontextprotocol/express express

# Hono 集成：
npm install @modelcontextprotocol/hono hono

快速开始

以下是一个 MCP 服务器的示例。这个最小示例通过 stdio 暴露了一个名为 greet 的工具：

import { McpServer } from '@modelcontextprotocol/server';
import { StdioServerTransport } from '@modelcontextprotocol/server/stdio';
import * as z from 'zod/v4';

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

server.registerTool(
    'greet',
    {
        description: '按名称向某人打招呼',
        inputSchema: z.object({ name: z.string() })
    },
    async ({ name }) => ({
        content: [{ type: 'text', text: `你好，${name}！` }]
    })
);

async function main() {
    const transport = new StdioServerTransport();
    await server.connect(transport);
}

main();

准备构建真实项目？请跟随逐步教程：

• 构建你的第一个服务器——一个 stdio 天气预警服务器，从 npm init 到工具调用
• 构建你的第一个客户端——连接到该服务器，列出其工具并调用它们

有关教程之外的可运行端到端示例，请参见：

• examples/README.md——可运行、自验证的客户端/服务器示例对（每个目录一个独立故事）

文档

• 构建服务器——你的第一个 MCP 服务器，逐步指导
• 构建客户端——你的第一个 MCP 客户端，逐步指导
• 文档站点——完整指南：工具、资源、提示、通过 HTTP 和 stdio 提供服务、客户端、OAuth 和迁移
• 故障排除——常见错误及其修复方法
• API 参考
• MCP 文档
• MCP 规范

本地构建文档

要在本地处理文档站点：

pnpm docs:api      # 生成 API 参考 markdown（输出：docs/api/）
pnpm docs:dev      # 启动 V2 站点的 VitePress 开发服务器
pnpm docs:build    # 构建 V2 站点（输出：docs/.vitepress/dist/）
pnpm docs:multi    # 构建 V1 + V2 合并站点（输出：tmp/docs-combined/）

docs:multi 脚本从当前检出构建 V2 站点，通过 git worktree 签出 v1.x 分支以构建 V1 站点，并生成一个包含 V1 文档（根目录）和 V2 文档（位于 /v2/ 下）的合并站点。

v1（遗留）文档和修复

如果您使用的是 SDK 的 v1 版本，v1 API 文档位于 https://ts.sdk.modelcontextprotocol.io/。v1 源代码和任何 v1 特定的修复存在于长期维护的 v1.x 分支。V2 API 文档位于 /v2/。

贡献

欢迎在 GitHub 上提交 Issue 和拉取请求：https://github.com/modelcontextprotocol/typescript-sdk。

许可证

本项目新贡献采用 Apache License 2.0 许可，现有代码采用 MIT 许可。详见 LICENSE 文件。