从零开始开发一个 MCP Server！保姆级教程！

海艄公 發表於 2025-4-30 09:09:00

从零开始开发一个 MCP Server！保姆级教程！

大家好，我是R哥。
之前分享了一篇 MCP 的介绍及使用：
<blockquote>
最近热火朝天的 MCP 是什么鬼？如何使用MCP？一文给你讲清楚！
</blockquote>
这篇文章得到了大家的广泛阅读，让大家对 MCP 的概念和使用也有了一个基础的认知，也介绍了如何使用 MCP Server，这篇再来介绍下如何从 0 开发一个自己的 MCP Server。
MCP 本质上是为 AI 大模型提供调用外部工具的能力，MCP Server 就是这个能力的具体实现——你可以通过它，把你已有的 API、脚本、服务包装成 AI 能理解和调用的 MCP 工具。
这篇我们就以获取图片为例来创建一个 MCP Server，让 AI 根据自然语言来获取图片网站上的图片，比如 Pixabay 图片网站，它就提供了 API 可以让外界来搜索图片。
PixabayAPI 文档：
<blockquote>
https://pixabay.com/api/docs/
</blockquote>
MCP 官方提供了 Python、Node、Java、Kotlin 等 SDK 接入，我们为了方便测试使用，本文以 Node 为例进行演示，请确保你安装了最新版本的 Node。
<h2 id="安装-node-环境">安装 Node 环境</h2>
如果你还没有安装 Node.js 和 npm，你可以从 nodejs.org 下载并安装，然后验证 Node.js 是否正确安装：
<blockquote>
node --version
npm --version
</blockquote>
安装过程，略。
<h2 id="创建-mcp-server-项目">创建 MCP Server 项目</h2>
创建一个 MCP Server 项目：
<blockquote>
mkdir pixabay
cd pixabay
</blockquote>
初始化一个新的 npm 项目：
<blockquote>
npm init -y
</blockquote>
安装相关依赖：
<blockquote>
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript
</blockquote>
创建主要目录和文件：
<blockquote>
mkdir src
touch src/index.ts
</blockquote>
更新 package.json 文件，添加以下主要配置项：
<pre><code class="language-json">{
"type": "module",
"bin": {
"pixabay": "./build/index.js"
},
"scripts": {
"build": "tsc && chmod 755 build/index.js"
},
"files": [
"build"
],
}
</code></pre>
在根目录创建 tsconfig.json 文件，内容如下：
<pre><code class="language-json">{
"compilerOptions": {
"target": "ES2022",
"module": "Node16",
"moduleResolution": "Node16",
"outDir": "./build",
"rootDir": "./src",
"strict": true,
"esModuleInterop": true,
"skipLibCheck": true,
"forceConsistentCasingInFileNames": true
},
"include": ["src/**/*"],
"exclude": ["node_modules"]
}
</code></pre>
到此，项目初始化完成，现在让我们开始构建一个图片搜索的 MCP 服务器吧。
<h2 id="构建-mcp-server">构建 MCP Server</h2>
在项目 <code>index.ts</code> 文件中添加 MCP Server：
<pre><code class="language-typescript">// MCP - NODE SDK
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";

// 导入 StdioServerTransport 类，用于处理服务器的输入输出通信
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";

// 导入用于验证输入参数的库
import { z } from "zod";

// Pixabay API URL
const baseUrl = "https://pixabay.com/api/";

/**
* 定义了 MCP Server 实例。
*/
const server = new McpServer({
name: "pixabay",
version: "1.0.0",
capabilities: {
 resources: {},
 tools: {},
},
});

/**
* 定义了一个名为 "pixabay-image-search" 的工具。
* 该工具接受一个查询字符串和一个图像类型作为输入参数，
* 并返回一个包含图像信息的 JSON 字符串。
*/
server.tool(
'pixabay-image-search',
{
 query: z.string(),
 type: z.string()
},
async ({ query, type = 'all' }) => {
 try {
 // 检查是否设置了 PIXABAY_KEY 环境变量
 if (!process.env.PIXABAY_KEY) {
 console.error("PIXABAY_KEY environment variable is not set");
 process.exit(1);
 }
 console.log("PIXABAY_KEY", process.env.PIXABAY_KEY);

 // 构建 Pixabay API 请求 URL
 const requestUrl = `${baseUrl}?key=${process.env.PIXABAY_KEY}&q=${query}&image_type=${type}&per_page=3`;

 // 发送请求并获取响应
 const response = await fetch(requestUrl);

 //检查响应状态
 const json = await response.json();

 // 返回响应结果
 return {
 content: [{
 type: 'text',
 text: JSON.stringify({
 images: json.hits || [],
 total_results: json.total,
 query,
 }, null, 2)
 }]
 }
 } catch (e) {
 return {
 content: [{
 type: 'text',
 text: `Error: ${e instanceof Error ? e.message : 'Unknown error'}`
 }],
 isError: true
 };
 }
}
)

/**
* 启动服务器并建立与传输层的连接。
* 该函数创建一个标准输入输出的服务器传输实例，
* 并使用该实例将服务器连接到传输层。
*/
async function startServer() {
// 创建一个标准输入输出的服务器传输实例，用于处理服务器的输入输出通信
const transport = new StdioServerTransport();

// 等待服务器通过指定的传输实例建立连接
await server.connect(transport);
}

// 启动服务器
startServer();
</code></pre>
这里主要定义了一个 McpServer，然后添加了一个名为 <code>pixabay-image-search</code> 的 MCP Tool 工具，用来从 Pixabay 根据关键字和类型搜索图片。
最后使用以下命令进行构建：
<blockquote>
npm run build
</blockquote>
根据之前的项目定义，最终会在 build 目录中构建为 index.js 文件。
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090903163-2125713929.png">
<h2 id="调试-mcp-server">调试 MCP Server</h2>
官方提供了一个 Inspector 调试工具，它是一款用于测试和调试 MCP 服务器的交互式开发者工具，详细介绍和使用方法如下：
<blockquote>
https://modelcontextprotocol.io/docs/tools/inspector
</blockquote>
启动调试参考命令：
<blockquote>
sudo npx @modelcontextprotocol/inspector node build/index.js
</blockquote>
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090903766-1657649213.png">
启动成功后，访问以下地址：
<blockquote>
http://127.0.0.1:6274/
</blockquote>
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090904899-1993465440.png">
这个界面主要分为三个区域：
<ul>
<li>左侧进行环境变量配置、MCP Server 连接/重启等操作；</li>
<li>中间选择要调试的 MCP 工具；</li>
<li>右侧对选择的 MCP 工具进行调试。</li>
</ul>
如图，测试成功。
<h2 id="在工具中使用-mcp-server">在工具中使用 MCP Server</h2>
<h3 id="在-claude-for-desktop-中使用">在 Claude for Desktop 中使用</h3>
首先需要安装 Claude 桌面版，安装地址如下：
<blockquote>
https://claude.ai/download
</blockquote>
然后打开以下配置文件：
<blockquote>
~/Library/Application Support/Claude/claude_desktop_config.json
</blockquote>
添加 MCP Server 配置：
<pre><code class="language-json">{
"mcpServers": {
 "pixabay": {
 "command": "node",
 "args": [
 "../pixabay/build/index.js"
 ],
 "env": {
 "PIXABAY_KEY": "..."
 }
 }
}
}
</code></pre>
注意，请替换成自己的 index.js 文件全路径和 PIXABAY_KEY。
然后再重启 Claude 桌面软件，可以看到有一个 MCP 工具可用：
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090905270-868200282.png">
然后我们发起测试一下：
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090905727-1369235819.png">
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090906303-1218708600.png">
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090906838-791034498.jpg">
成功通过自然语言获取到了猫吃饭的图片，通过Claude for Desktop 测试自定义的 MCP Server 调用成功。
<h3 id="在-vs-code-中使用">在 VS Code 中使用</h3>
在 VS Code 中只需要安装一个 ROO CODE 插件，不懂的请先看这篇：
<blockquote>
DeepSeek 装进 VSCode，编程非常丝滑！
</blockquote>
然后添加 MCP 图标配置 MCP Server：
<pre><code class="language-json">{
"mcpServers": {
"pixabay": {
 "command": "node",
 "args": [
 "../pixabay/build/index.js"
 ],
 "env": {
 "PIXABAY_KEY": "..."
 }
}
}
}
</code></pre>
配置成功后如图所示：
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090907240-2063614816.png">
然后同样发起测试：
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090907764-651729820.png">
<img src="https://img2024.cnblogs.com/other/1218593/202504/1218593-20250430090908211-990891482.png">
成功通过自然语言获取到了猫吃饭的图片，通过VS Code 测试自定义的 MCP Server 调用成功。
在其他 AI 编程中使用 MCP Server 也是一样的道理，比如 Cursor，具体用法请参考这篇：
<blockquote>
最近热火朝天的 MCP 是什么鬼？如何使用 MCP？一文给你讲清楚！
</blockquote>
测试没问题后，我们就可以把代码发布到 npm 仓库供其他人使用了。
<h2 id="总结">总结</h2>
本文从 MCP Server 开发实战出发，完整演示了从零搭建一个 MCP Server 的流程。你不仅掌握了 MCP Server 的构建方式，也能体验到了 MCP 工具在开发者日常工作中带来的提效魔法。
重点回顾如下：
<ul>
<li>MCP Server 是大模型调用外部服务的桥梁；</li>
<li>通过 Node.js 和官方 SDK 快速开发 MCP Server；</li>
<li>利用 <code>Inspector</code> 工具调试，所见即所得；</li>
<li>轻松集成到 Claude、VS Code、Cursor 等 AI 工具中；</li>
</ul>
这不仅是一次 MCP 技术实战，也是一种新的编程范式的探索，让 AI 通过 MCP 调用我们的代码，把人类的创意和机器的执行力结合起来。
你也可以尝试把更多的业务能力封装成 MCP 工具，比如：商品推荐、新闻摘要、天气预报，甚至接入自己的数据库或私有系统等等，让 AI 真正成为我们日常工作中的得力助手。
未完待续，下篇我继续研究和分享更有趣的 AI + MCP 应用场景和实战，关注「AI技术宅」公众号和R哥一起学 AI。
<blockquote>
版权声明： 本文系公众号 "AI技术宅" 原创，转载、引用本文内容请注明出处，抄袭、洗稿一律投诉侵权，后果自负，并保留追究其法律责任的权利。
</blockquote>
更多文章推荐：
1.Spring Boot 3.x 教程，太全了！
2.3,000+ 道 Java面试题及答案整理(最新版)
3.免费获取 IDEA 激活码的 7 种方式（最新版）
4.Java & DeepSeek & AI 学习资料分享
5.程序员精美简历模板分享
觉得不错，别忘了随手点赞+转发哦！

</div>
<div id="MySignature" role="contentinfo">

<div style="clear: both"></div> 
来源：https://www.cnblogs.com/javastack/p/18854880

頁: [1]

琼殿技术论坛's Archiver

从零开始开发一个 MCP Server！保姆级教程！