本文将指导你使用 Node.js 和 IntelliJ IDEA 创建并运行一个简单的 MCP(Model Context Protocol)服务端和客户端。示例使用 TypeScript 和 @modelcontextprotocol/sdk,通过 Stdio 协议实现通信。服务端提供一个加法工具,客户端列出工具并调用它。适合初学者快速入门 MCP 开发。
前提条件
-
Node.js:建议 v16 或以上,安装后运行 node --version 确认。
-
IntelliJ IDEA:配置好 Node.js 和 TypeScript 支持,推荐IntelliJ IDEA 2024.3.5 (Ultimate Edition),太老了无法直接执行tsx。

-
依赖:
- @modelcontextprotocol/sdk:MCP SDK。
- zod:用于输入验证。
- tsx:运行 TypeScript 文件。
-
基础的 TypeScript 知识。
项目设置
-
创建项目:
- 打开 IntelliJ IDEA,选择 File > New > Project,选择 Node.js 项目模板。
- 项目命名为 mcp-quickstart,选择 Node.js 版本,点击 Create。
-
安装依赖:
-
打开终端(IDEA 底部 Terminal),运行:
kotlinnpm init -y npm install @modelcontextprotocol/sdk zod tsx --save-dev
-
-
配置 TypeScript:
-
在项目根目录创建 tsconfig.json:
json{ "compilerOptions": { "target": "ESNext", "module": "CommonJS", "strict": true, "esModuleInterop": true, "skipLibCheck": true, "forceConsistentCasingInFileNames": true, "outDir": "./dist" }, "include": ["*.ts"] }
-
创建 MCP 服务端
创建一个简单的 MCP 服务端,提供一个加法工具。
-
新建文件 McpServer.ts:
-
在项目根目录创建 McpServer.ts,添加以下代码:
javascriptimport { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js' import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js' import { z } from 'zod' // Create an MCP server const server = new McpServer({ name: 'demo-server', version: '1.0.0' }) // Add an addition tool server.registerTool( 'add', { title: 'Addition Tool', description: 'Add two numbers', inputSchema: { a: z.number(), b: z.number() } }, async ({ a, b }) => ({ content: [{ type: 'text', text: String(a + b) }] }) ) // Add a dynamic greeting resource server.registerResource( 'greeting', new ResourceTemplate('greeting://{name}', { list: undefined }), { title: 'Greeting Resource', // Display name for UI description: 'Dynamic greeting generator' }, async (uri, { name }) => ({ contents: [ { uri: uri.href, text: `Hello, ${name}!` } ] }) ) // 启动服务器 async function startServer() { try { const transport = new StdioServerTransport() await server.connect(transport) console.error('MCP 服务器在 Stdio 上运行...') } catch (error) { console.error('服务器错误:', error) process.exit(1) } } startServer().catch((error) => { console.error('主程序错误:', error) process.exit(1) })
-
-
代码说明:
- 创建一个名为demo-server 的 MCP 服务器。
- 注册一个 add 工具,接受两个数字(a 和 b),返回它们的和。
- 使用 StdioServerTransport 通过标准输入/输出通信。
创建 MCP 客户端
创建一个客户端,连接服务端,列出工具并调用加法工具。
-
新建文件 McpClient.ts:
-
在项目根目录创建 McpClient.ts,添加以下代码:
javascript#!/usr/bin/env node import { Client } from '@modelcontextprotocol/sdk/client/index.js' import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js' // 客户端设置 const client = new Client({ name: 'example-client', version: '1.0.0' }) // 客户端逻辑:连接服务器并与之交互 async function startClient() { try { // 使用命令和参数方式初始化传输层 const transport = new StdioClientTransport({ command: 'npx.cmd', args: ['tsx', 'McpServer.ts'] }) await client.connect(transport) console.log('已连接到 MCP 服务器:', client.serverInfo?.name || '未知') // 列出可用工具 const toolsList = await client.listTools() console.log( '可用工具:', toolsList.tools.map((t) => t.name) ) // 调用加法工具 if (toolsList.tools.some((t) => t.name === 'add')) { const result = await client.callTool({ name: 'add', arguments: { a: 5, b: 3 } }) console.log('加法结果:', result.content[0].text) } // 断开客户端连接 await client.close() console.log('客户端已断开连接。') } catch (error) { console.error('客户端错误:', error) process.exit(1) } } startClient().catch((error) => { console.error('主程序错误:', error) process.exit(1) })
-
-
代码说明:
- 创建一个名为 example-client 的 MCP 客户端。
- 使用 spawn 启动服务器进程(McpServer.ts),通过 tsx 运行。
- 通过 StdioClientTransport 连接服务器,列出工具并调用 add 工具(输入 a=5, b=3)。
- 包含错误处理和进程清理。
在 IntelliJ IDEA 中运行
- 右键文件运行:

-
创建运行配置:
-
点击 Run > Edit Configurations。
-
点击 + 添加新配置,选择 Node.js。
-
设置以下字段:
- Name:MCP Client
- Node interpreter:选择你的 Node.js 路径(运行 which node 确认)。
- TypeScript Loader: 选择Boudled(tsx),只有选择这个才能直接运行。
- Node parameters:留空。
- File:选择 node_modules/tsx/dist/cli.js(tsx 的入口)。
-
保存配置。
-

-
运行客户端:
-
点击 IDEA 顶部绿色三角形(Run),选择 MCP Client。
-
或者在终端运行:
npx tsx McpClient.ts
-
预期输出:
less
MCP 服务器在 Stdio 上运行...
已连接到 MCP 服务器: 未知
可用工具: [ 'add' ]
加法结果: 8
客户端已断开连接。
调试常见问题
-
错误: The "path" argument must be of type string:
-
确认 mcp-client.ts 中使用 spawn("npx.cmd", ["tsx", "mcp-server.ts"], { shell: true })(Windows 环境)。
-
确保 tsx 已安装:
cssnpm install --save-dev tsx
-
-
错误: McpError: Cannot read properties of null (reading '_def'):
-
确保 @modelcontextprotocol/sdk 和 zod 版本最新:
javanpm install @modelcontextprotocol/sdk@latest zod@latest
-
检查 mcp-server.ts 中的 addToolSchema 是否正确定义。
-
-
服务器名称显示"未知" :
-
确认 mcp-server.ts 中 McpServer 的 name 字段设置为 "example-server"。
-
在客户端添加调试日志:
arduinoconsole.log("服务器信息:", client.serverInfo);
-
总结
通过以上步骤,你在 IntelliJ IDEA 中成功搭建并运行了一个简单的 MCP 服务端和客户端。服务端提供了一个加法工具,客户端通过 Stdio 协议调用它。这个示例展示了 MCP 的核心功能,适合快速入门。你可以进一步扩展工具功能或尝试其他协议(如 WebSocket)。