从零搭建本地 MCP 服务：STDIO 模式实现与大模型集成全指南

95次阅读

之前已经介绍过了 MCP 了，如果你有兴趣可以查看下之前的文章：

MCP 模型上下文协议：解决 LLM 应用开发痛点的完整指南

目前很多官方都开发出了自己的 MCP 服务，例如 Gitlab，支付宝，高德地图，都提供了 MCP 服务，如果你具备开发能力，你也可以搭建自己的 MCP 服务，本文教你如何搭建自己的 MCP 服务。我们来看看 MCP 服务是如何工作的。

随着大模型应用场景的深化，官方与企业纷纷推出定制化 MCP（Model Context Protocol）服务，GitLab 用于代码协作场景的工具调用、支付宝面向支付场景的功能扩展、高德地图针对地理位置服务的集成，均通过 MCP 协议实现了大模型与垂直工具的联动。对于具备开发能力的用户，无需依赖第三方服务，可自主搭建符合业务需求的 MCP 服务。本文将从 MCP 工作原理切入，以 STDIO 传输模式为例，完整讲解本地 MCP 服务的搭建、测试及与大模型（以 Cursor 为例）的集成流程，助力开发者快速掌握 MCP 协议的实践应用。

一、MCP 服务核心工作原理：传输方式解析

MCP 协议的核心价值在于建立大模型与外部工具的通信桥梁，其传输方式直接决定了服务的适配场景与数据交互效率。目前主流的 MCP 传输方式分为 STDIO 和 SSE 两种，二者在通信模式、适用场景上存在显著差异，开发者需根据业务需求选择合适的方式。

1. STDIO 传输模式

STDIO（Standard Input/Output）即标准输入输出流，通过命令行的输入（stdin）与输出（stdout）实现数据交换。

通信特点：基于本地进程间通信，无网络依赖，数据传输延迟低，适合本地工具与大模型的轻量集成。
适用场景：本地脚本工具（如计算工具、文件处理工具）、无需跨设备调用的场景，例如本文将实现的本地加法运算工具。

2. SSE 传输模式

SSE（Server-Sent Events）基于 HTTP 协议实现单向通信，仅支持服务器向客户端主动推送数据。

通信特点：依赖网络环境，可实现跨设备、跨终端的工具调用，支持实时数据推送（如日志更新、实时计算结果）。
适用场景：云端工具服务（如在线数据分析工具、远程 API 调用）、需要持续推送数据的场景，例如实时监控系统与大模型的集成。

二、STDIO 模式 MCP 服务搭建：从环境准备到代码实现

本节将以“大模型触发加法运算”为需求，基于 Node.js 环境搭建 STDIO 模式的 MCP 服务，核心依赖官方 MCP SDK（@modelcontextprotocol/sdk）实现服务初始化与工具定义，同时使用 zod 库完成参数校验，确保输入数据的合法性。

1. 前置环境准备

搭建 MCP 服务前需完成基础开发环境配置，确保依赖工具正常运行：

安装 Node.js 与 npm：推荐使用 Node.js 16.x 及以上版本，可通过 node -v 和npm -v命令验证安装结果。
安装 pnpm 包管理器：相较于 npm，pnpm 具备更快的依赖安装速度与更小的磁盘占用，执行 npm install -g pnpm 完成全局安装。
了解核心依赖库：
- @modelcontextprotocol/sdk：官方 MCP 开发工具包，提供服务初始化、工具注册、传输协议封装等核心能力。
- zod：TypeScript 优先的数据验证库，用于定义工具输入参数的格式（如数字类型校验），避免非法参数导致服务异常。

2. 项目初始化与依赖安装

按照以下步骤创建项目目录并安装核心依赖：

创建项目文件夹：执行mkdir add-mcp && cd add-mcp，创建名为“add-mcp”的项目目录并进入。
初始化项目配置：执行 pnpm init，生成package.json 文件，用于管理项目依赖与配置。
安装核心依赖：执行pnpm add @modelcontextprotocol/sdk zod，将 MCP SDK 与参数校验库添加到项目依赖。
配置 ES Module 语法：在 package.json 中添加 "type": "module"，确保项目支持import/export 模块化语法，避免 CommonJS 与 ES Module 混用导致的报错。

3. 编写 MCP 服务核心代码（index.mjs）

创建 index.mjs 文件，通过 MCP SDK 实现服务初始化、加法工具注册，并配置 STDIO 传输模式，代码逐段解析如下：

// 导入 MCP 服务核心模块与 STDIO 传输模块
import {McpServer, ResourceTemplate} from "@modelcontextprotocol/sdk/server/mcp.js";
import {StdioServerTransport} from "@modelcontextprotocol/sdk/server/stdio.js";
// 导入 zod 用于参数校验
import {z} from "zod";

// 1. 初始化 MCP 服务：定义服务名称与版本，便于后续识别与管理
const server = new McpServer({
  name: "Addition-MCP-Service", // 服务名称，需与客户端配置对应
  version: "1.0.0" // 服务版本，用于迭代管理
});

// 2. 注册加法工具：定义工具名称、描述、参数格式与执行逻辑
server.tool(
  "add", // 工具唯一标识，大模型将通过此名称调用工具
  "Calculate the sum of two numbers (a and b)", // 工具描述，帮助大模型理解工具功能
  {a: z.number(), b: z.number()}, // 参数校验规则：a 和 b 必须为数字类型
  async ({a, b}) => { // 工具执行逻辑：接收参数并返回计算结果
    return {content: [{ type: "text", text: `The sum of ${a} and ${b} is: ${a + b}` }] // 结果格式，支持文本、JSON 等类型
    };
  }
);

// 3. 启动服务：配置 STDIO 传输并监听数据交互
async function main() {const transport = new StdioServerTransport(); // 初始化 STDIO 传输实例
  await server.connect(transport); // 建立服务与 STDIO 传输的连接
  console.log("STDIO-MCP Service started successfully. Waiting for tool calls...");
}

// 执行启动函数
main().catch(err => {console.error("MCP Service startup failed:", err.message);
});

代码核心逻辑说明：

服务初始化：通过 McpServer 类定义服务元信息，确保客户端能准确识别服务。
工具注册：server.tool()方法是核心，其中 zod 校验规则可防止非数字参数传入，避免计算错误；返回结果采用标准化格式，便于大模型解析。
STDIO 传输：StdioServerTransport类封装了标准输入输出流的处理，无需手动管理流的读写，降低开发复杂度。

三、MCP 服务测试：使用 Inspector 工具验证功能

服务搭建完成后，需通过官方测试工具 @modelcontextprotocol/inspector 验证工具是否正常响应，避免直接集成大模型时因服务异常导致排查困难。测试流程分为“启动测试工具”“连接服务”“调用工具”三步。

1. 启动 Inspector 测试工具

无需安装额外依赖，直接通过 npx 执行官方测试工具：

npx @modelcontextprotocol/inspector node index.mjs

执行命令后，工具将自动启动本地服务，并提示访问地址：http://127.0.0.1:6274/。

2. 连接 MCP 服务并测试工具

打开浏览器访问http://127.0.0.1:6274/，按照以下步骤完成测试：

连接服务：点击页面左上角的“Connect”按钮，若连接成功，按钮状态将变为“Connected”，同时控制台将输出“Client connected”日志。
列出工具：点击“List Tools”按钮，页面将显示已注册的工具列表（本文中为“add”工具），验证工具注册成功。
调用加法工具：
- 在工具列表中点击“add”工具，弹出参数输入框。
- 输入测试参数（如a=10，b=20），点击“Run Tool”按钮。
- 查看返回结果：页面将显示“The sum of 10 and 20 is: 30”，说明工具执行正常；若输入非数字参数（如 a="abc"），将触发zod 校验报错，验证参数校验功能有效。

四、大模型集成：以 Cursor 为例配置 MCP 服务

测试通过后，即可将本地 MCP 服务集成到大模型中，实现“大模型自动识别需求→调用 MCP 工具→返回结果”的完整流程。本节以 Cursor（代码场景常用大模型）为例，讲解客户端配置步骤与功能验证。

1. Cursor 客户端 MCP 配置

Cursor 通过配置文件关联本地 MCP 服务，需按照以下步骤修改配置：

打开 Cursor 配置文件：进入 Cursor 设置（Settings），找到“MCP Servers”配置项，点击“Edit Config”进入 JSON 配置界面。
添加 MCP 服务配置：在 mcpServers 对象中新增“add-mcp”服务配置，示例如下：

json

{
  "mcpServers": {
    "add-mcp": { // 服务名称，自定义且需唯一
      "type": "stdio", // 传输方式，与服务端一致（STDIO）"command": "npx", // 启动命令，用于执行 MCP 服务
      "args": [
        "-y", // pnpm/npx 参数，自动确认安装依赖
        "node", // 执行 Node.js 脚本
        "D:\\kelen\\study\\add-mcp\\index.mjs" // 本地 MCP 服务代码路径（需替换为实际路径）]
    }
  }
}

验证配置有效性：保存配置后，Cursor 将自动尝试连接 MCP 服务，若配置正确，服务名称旁将显示“绿色指示灯”，表示连接成功；若显示红色，需检查路径是否正确、服务是否能正常启动。

2. 验证大模型工具调用效果

配置完成后，在 Cursor 对话界面输入加法相关问题，测试大模型是否能自动调用 MCP 工具：

输入问题：“计算 156 加 248 的结果”。
观察响应：Cursor 将识别到“加法运算”需求，自动调用“add-mcp”服务，返回结果“The sum of 156 and 248 is: 404”，无需手动执行计算，实现工具与大模型的无缝联动。

五、总结与扩展：MCP 服务的价值与进阶方向

本文通过“原理解析→搭建实现→测试→集成”的流程，完成了 STDIO 模式 MCP 服务的落地，核心价值在于验证了 MCP 协议的灵活性 —— 开发者可基于业务需求定制工具，摆脱对第三方服务的依赖，同时实现大模型“自主决策调用工具”的智能化能力，显著提升工作效率（如自动计算、数据处理、API 调用等场景）。

进阶扩展方向

工具功能扩展：在现有服务基础上，新增乘法、除法等计算工具，或集成外部 API（如天气查询、股票数据接口），通过 server.tool() 注册更多工具，满足复杂需求。
传输方式切换：若需实现跨设备调用，可将 STDIO 模式改为 SSE 模式，修改 StdioServerTransport 为SseServerTransport，并配置 HTTP 端口，支持远程客户端连接。
错误处理优化：在工具执行逻辑中添加异常捕获（如除数为零、API 调用失败），通过 zod 扩展参数校验规则（如数值范围限制），提升服务稳定性。
多模型集成：除 Cursor 外，可将 MCP 服务集成到 ChatGPT、文心一言等大模型中，多数支持 MCP 协议的大模型均提供类似的配置入口，流程与 Cursor 一致。

正文完