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

最新推荐文章于 2025-09-17 17:22:59 发布

原创最新推荐文章于 2025-09-17 17:22:59 发布 · 2.5k 阅读

18 ·

CC 4.0 BY-SA版权

文章标签：

#arcgis #langchain #人工智能 #AI大模型 #大模型微调 #AI #MCP

这篇文章得到了大家的广泛阅读，让大家对 MCP 的概念和使用也有了一个基础的认知，也介绍了如何使用 MCP Server，这篇再来介绍下如何从 0 开发一个自己的 MCP Server。

MCP 本质上是为 AI 大模型提供调用外部工具的能力，MCP Server 就是这个能力的具体实现——你可以通过它，把你已有的 API、脚本、服务包装成 AI 能理解和调用的 MCP 工具。

这篇我们就以获取图片为例来创建一个 MCP Server，让 AI 根据自然语言来获取图片网站上的图片，比如 Pixabay 图片网站，它就提供了 API 可以让外界来搜索图片。

Pixabay API 文档：

https://pixabay.com/api/docs/

MCP 官方提供了 Python、Node、Java、Kotlin 等 SDK 接入，我们为了方便测试使用，本文以 Node 为例进行演示，请确保你安装了最新版本的 Node。

安装 Node 环境

如果你还没有安装 Node.js 和 npm，你可以从 nodejs.org 下载并安装，然后验证 Node.js 是否正确安装：

node --version

npm --version

安装过程，略。

创建 MCP Server 项目

创建一个 MCP Server 项目：

mkdir pixabay

cd pixabay

初始化一个新的 npm 项目：

npm init -y

安装相关依赖：

npm install @modelcontextprotocol/sdk zod

npm install -D @types/node typescript

创建主要目录和文件：

mkdir src

touch src/index.ts

更新 package.json 文件，添加以下主要配置项：

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

在根目录创建 tsconfig.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"]
}

到此，项目初始化完成，现在让我们开始构建一个图片搜索的 MCP 服务器吧。

构建 MCP Server

在项目 index.ts 文件中添加 MCP Server：

// 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
            };
        }
    }
)

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

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

// 启动服务器
startServer();

这里主要定义了一个 McpServer，然后添加了一个名为 pixabay-image-search 的 MCP Tool 工具，用来从 Pixabay 根据关键字和类型搜索图片。

最后使用以下命令进行构建：

npm run build

根据之前的项目定义，最终会在 build 目录中构建为 index.js 文件。

在这里插入图片描述

调试 MCP Server

官方提供了一个 Inspector 调试工具，它是一款用于测试和调试 MCP 服务器的交互式开发者工具，详细介绍和使用方法如下：

https://modelcontextprotocol.io/docs/tools/inspector

启动调试参考命令：

sudo npx @modelcontextprotocol/inspector node build/index.js

在这里插入图片描述

启动成功后，访问以下地址：

http://127.0.0.1:6274/

在这里插入图片描述

这个界面主要分为三个区域：

左侧进行环境变量配置、MCP Server 连接/重启等操作；
中间选择要调试的 MCP 工具；
右侧对选择的 MCP 工具进行调试。

如图，测试成功。

在工具中使用 MCP Server

在 Claude for Desktop 中使用

首先需要安装 Claude 桌面版，安装地址如下：

https://claude.ai/download

然后打开以下配置文件：

~/Library/Application Support/Claude/claude_desktop_config.json

添加 MCP Server 配置：

{
    "mcpServers": {
        "pixabay": {
            "command": "node",
            "args": [
                "../pixabay/build/index.js"
            ],
            "env": {
                "PIXABAY_KEY": "..."
            }
        }
    }
}

注意，请替换成自己的 index.js 文件全路径和 PIXABAY_KEY。

然后再重启 Claude 桌面软件，可以看到有一个 MCP 工具可用：

在这里插入图片描述

然后我们发起测试一下：

在这里插入图片描述

成功通过自然语言获取到了猫吃饭的图片，通过 Claude for Desktop 测试自定义的 MCP Server 调用成功。

在 VS Code 中使用

在 VS Code 中只需要安装一个 ROO CODE 插件，不懂的请先看这篇：

DeepSeek 装进 VSCode，编程非常丝滑！

然后添加 MCP 图标配置 MCP Server：

{
  "mcpServers": {
    "pixabay": {
      "command": "node",
      "args": [
        "../pixabay/build/index.js"
      ],
      "env": {
        "PIXABAY_KEY": "..."
      }
    }
  }
}

配置成功后如图所示：

在这里插入图片描述