本章目录如下：

1. 《Gradio全解13——MCP协议详解（1）——MCP协议介绍与架构组件》
2. 《Gradio全解13——MCP协议详解（2）——MCP能力协商与通信机制》
3. 《Gradio全解13——MCP协议详解（3）——TypeScript介绍：特点、适用领域与实战》
4. 《Gradio全解13——MCP协议详解（4）——TypeScript包命令：npm与npx》
5. 《Gradio全解13——MCP协议详解（5）——Python包命令：uv与uvx实战》
6. 《Gradio全解13——MCP协议详解（6）——MCP服务器构建、测试与示例大全》
7. 《Gradio全解13——MCP协议详解（7）——MCP客户端》
8. 《Gradio全解13——MCP协议详解（8）——MCP六大​功能特性》
9. 《Gradio全解13——MCP协议详解（9）——MCP Inspector》

第13章 MCP协议详解

MCP是当前人工智能领域最热门技术之一，是实现大模型快速应用的捷径。本章将基于MCP最新方案修订版：2025-06-18，详细讲解MCP协议细节，内容包括MCP协议介绍与架构组件、MCP能力协商与通信机制、TypeScript介绍：特点、适用领域与实战、TypeScript包命令npm与npx、Python包命令uv与uvx、MCP服务器构建测试与示例大全、MCP客户端、六大​功能特性和调试工具MCP Inspector。

13.6 MCP服务器构建、测试与示例大全

下面将演示如何运用大语言模型辅助开发定制化的MCP服务端与客户端，内容包括构建天气服务器、安装并测试Claude for Desktop，同时展示网络上其它可用的MCP服务器示例。本教程以Claude为例，但该方案同样适用于其它前沿大语言模型。

13.6.1 开发MCP天气服务器

本节面向MCP服务端开发者，展示如何快速构建专属服务端并与Claude桌面版等客户端集成。首先概述天气服务器，然后在安装Node.js并设置环境后，构建MCP天气服务器。

1. 天气服务器概述

我们将开发一个简易的MCP气象服务端，示例从基础配置起步，逐步实现复杂业务场景。本项目目标是：通过MCP协议，解决当前多数大语言模型无法直接获取天气预报与灾害警报的痛点！服务器具体实现功能有：

• 暴露两个标准化工具接口：get-alerts（获取灾害警报）和get-forecast（获取天气预报）。
• 通过客户端配置接入MCP宿主环境Claude for Desktop。

服务器可连接任意客户端，如自定义构建客户端或其它已有客户端见13.7节。

一般情况下，MCP服务器可提供三种主要能力：

• 资源(Resources)：客户端可读取的类文件数据（如API响应或文件内容）。
• 工具(Tools)：可由LLM调用的函数（需用户授权）。
• 提示(Prompts)：帮助用户完成特定任务的预编写模板。

这部分会在13.8节讲解，本教程将主要关注工具部分。下面开始准备工作：安装Node.js并设置环境。

2. 安装Node.js并设置环境

本快速入门指南要求读者具备以下基础知识：TypeScript编程语言和Claude 等大语言模型(LLM)的基本概念。系统环境要求已安装16或更高版本的Node.js ，官网下载地址：nodejs.org 。安装完成后，请通过命令行验证Node.js是否安装。Windows系统下，按下Windows+R键，单击Enter键，在命令行中输入以下命令验证Node.js安装：

>node --version  # v22.16.0
>npm --version  # 10.9.2

若显示"command not found"或"node is not recognized"错误，请从nodejs.org下载并安装Node.js。现在，让我们创建并设置项目：

# Create a new directory for our project
md weather
cd weather
# Initialize a new npm project
npm init -y
# Install dependencies
npm install @modelcontextprotocol/sdk zod
npm install -D @types/node typescript
# Create our files
md src
powershell new-item src\index.ts

其中npm安装命令中，@types/node - Node.js是TypeScript类型定义包，提供Node.js API的类型信息。typescript是TypeScript 编译器包。@modelcontextprotocol/sdk表示MCP的软件开发工具包，zod是TypeScript优先的模式验证库。参数简写-D等同于--save-dev，表示将包安装为开发依赖。
然后，更新初始化时生成的package.json。保留其他信息的同时，添加type、bin、scripts和files四条信息：

{"type": "module","bin": {"weather": "./build/index.js"},"scripts": {"build": "tsc && node -e \"require('fs').chmodSync('build/index.js', '755')\""},"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"]
}

现在，让我们开始构建天气服务器，完整代码参见：A Simple MCP weather Server written in TypeScript。

3. 构建服务器

​构建服务器大致分为下面几步：导入包并设置实例、定义帮助函数、定义执行工具，最后启动服务器。各步骤代码如下：

1. 导入包并设置实例。将这些代码添加到src/index.ts的顶部：

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
const NWS_API_BASE = "https://api.weather.gov";
const USER_AGENT = "weather-app/1.0";
// Create server instance
const server = new McpServer({name: "weather",version: "1.0.0",capabilities: {resources: {},tools: {},},
});

2. 定义辅助函数。辅助函数用于查询和格式化来自美国国家气象局API的数据：

// Helper function for making NWS API requests
async function makeNWSRequest<T>(url: string): Promise<T | null> {const headers = {"User-Agent": USER_AGENT,Accept: "application/geo+json",};try {const response = await fetch(url, { headers });if (!response.ok) {throw new Error(`HTTP error! status: ${response.status}`);}return (await response.json()) as T;} catch (error) {console.error("Error making NWS request:", error);return null;}
}interface AlertFeature {properties: {event?: string;areaDesc?: string;severity?: string;status?: string;headline?: string;};
}
interface AlertsResponse {features: AlertFeature[];
}
// Format alert data
function formatAlert(feature: AlertFeature): string {const props = feature.properties;return [`Event: ${props.event || "Unknown"}`,`Area: ${props.areaDesc || "Unknown"}`,`Severity: ${props.severity || "Unknown"}`,`Status: ${props.status || "Unknown"}`,`Headline: ${props.headline || "No headline"}`,"---",].join("\n");
}interface ForecastPeriod {name?: string;temperature?: number;temperatureUnit?: string;windSpeed?: string;windDirection?: string;shortForecast?: string;
}
interface ForecastResponse {properties: {periods: ForecastPeriod[];};
}
interface PointsResponse {properties: {forecast?: string;  # url };
}

3. 定义工具。工具负责实际执行处理逻辑：

// Register weather tools
server.tool("get-alerts","Get weather alerts for a state",{state: z.string().length(2).describe("Two-letter state code (e.g. CA, NY)"),},async ({ state }) => {const stateCode = state.toUpperCase();const alertsUrl = `${NWS_API_BASE}/alerts?area=${stateCode}`;const alertsData = await makeNWSRequest<AlertsResponse>(alertsUrl);if (!alertsData) {return {content: [{type: "text",text: "Failed to retrieve alerts data",},],};}const features = alertsData.features || [];if (features.length === 0) {return {content: [{type: "text",text: `No active alerts for ${stateCode}`,},],};}const formattedAlerts = features.map(formatAlert);const alertsText = `Active alerts for ${stateCode}:\n\n${formattedAlerts.join("\n")}`;return {content: [{type: "text",text: alertsText,},],};},
);server.tool("get-forecast","Get weather forecast for a location",{latitude: z.number().min(-90).max(90).describe("Latitude of the location"),longitude: z.number().min(-180).max(180).describe("Longitude of the location"),},async ({ latitude, longitude }) => {// Get grid point dataconst pointsUrl = `${NWS_API_BASE}/points/${latitude.toFixed(4)},${longitude.toFixed(4)}`;const pointsData = await makeNWSRequest<PointsResponse>(pointsUrl);if (!pointsData) {return {content: [{type: "text",text: `Failed to retrieve grid point data for coordinates: ${latitude}, ${longitude}. This location may not be supported by the NWS API (only US locations are supported).`,},],};}const forecastUrl = pointsData.properties?.forecast;if (!forecastUrl) {return {content: [{type: "text",text: "Failed to get forecast URL from grid point response data",},],};}// Get forecast dataconst forecastData = await makeNWSRequest<ForecastResponse>(forecastUrl);if (!forecastData) {return {content: [{type: "text",text: "Failed to retrieve forecast data",},],};}const periods = forecastData.properties?.periods || [];if (periods.length === 0) {return {content: [{type: "text",text: "No forecast periods available",},],};}// Format forecast periodsconst formattedForecast = periods.map((period: ForecastPeriod) =>[`${period.name || "Unknown"}:`,`Temperature: ${period.temperature || "Unknown"}°${period.temperatureUnit || "F"}`,`Wind: ${period.windSpeed || "Unknown"} ${period.windDirection || ""}`,`${period.shortForecast || "No forecast available"}`,"---",].join("\n"),);const forecastText = `Forecast for ${latitude}, ${longitude}:\n\n${formattedForecast.join("\n")}`;return {content: [{type: "text",text: forecastText,},],};},
);

4. 启动服务器。最后，实现运行服务器的主函数：

async function main() {const transport = new StdioServerTransport();await server.connect(transport);console.error("Weather MCP Server running on stdio");
}
main().catch((error) => {console.error("Fatal error in main():", error);process.exit(1);
});

完成代码后，执行命令npm run build构建服务器！这是确保服务器能够成功连接的关键步骤：

>npm run build
weather@1.0.0 build
tsc && node -e "require('fs').chmodSync('build/index.js', '755')"

13.6.2 安装Claude for Desktop

现在让我们安装MCP宿主环境Claude for Desktop，使用Claude for Desktop中的预构建服务器功能扩展Claude for Desktop的功能，包括：读取计算机文件系统、写入新文件、移动文件和搜索文件。需要注意，执行这些操作前需明确授权！

1. 安装Claude for Desktop

下载Claude for Desktop，链接：CLAUDE。选择对应版本下载：macOS版或Windows版（注：Linux平台暂不支持），然后按照说明完成安装。若已安装 Claude for Desktop，单击App左上角菜单，选择Help->Check for Updates，确保已升级至最新版本，如图13-5：

图13-5

2. 添加Filesystem MCP Server

我们将通过安装预构建的Filesystem MCP Server来添加文件系统功能，详见：Filesystem MCP Server。这是当前多个参考服务器之一，还有许多社区创建的服务器可选，详见13.6.4节。

配置步骤：打开Claude App，单击左上角菜单，选择File->Settings，在设置面板左侧栏点击「Developer」，然后点击「Edit Config」，这将创建配置文件至以下路径（若文件不存在）：

Windows: %APPDATA%\Claude\claude_desktop_config.json

使用任意文本编辑器打开配置文件，将其内容替换为以下配置：

{"mcpServers": {"filesystem": {"command": "npx","args": ["-y","@modelcontextprotocol/server-filesystem","C:\\Users\\username\\Desktop","C:\\Users\\username\\Downloads"]}}
}

请确保将username替换为计算机的实际用户名，配置路径必须指向希望Claude访问和修改的有效目录。默认设置已包含桌面（Desktop）和下载（Downloads）目录，读者也可以自行添加更多路径。注意：此功能同样需要计算机已安装Node.js。

配置文件工作原理：该配置文件指示Claude for Desktop在每次启动时运行哪些MCP服务器。本示例中添加了一个名为"filesystem"的服务器，即Filesystem MCP Server。该服务器将使用Node.js的npx命令安装并运行@modelcontextprotocol/server-filesystem模块，它将实现在Claude for Desktop中访问文件系统的功能。

命令权限说明：Claude for Desktop将以当前用户的账户权限执行配置文件中的命令并访问本地文件，所以请确保理解并信任命令来源后再进行添加。

3. 重启Claude并测试Filesystem

更新配置文件后，需要重启Claude for Desktop。重启后，可能需要等待几分钟，然后应在输入框左下角看到滑块图标“Search and tools”。单击该图标后，选择“filesystem”，应显示Filesystem MCP Server提供的工具列表，如图13-6：

图13-6

若服务器未被Claude for Desktop识别，请查看目录%APPDATA%\Claude\logs中的日志查找出错原因。

功能测试：现在我们可与Claude对话并进行文件系统操作，系统将自动识别何时调用相关工具。可尝试的指令示例：

• Can you write a poem and save it to my desktop?
• What are some work-related files in my downloads folder?
• Can you take all the images on my desktop and move them to a new folder called “Images”?

执行前，Claude会自动调用相应工具，每次操作前都会请求您的明确授权，如图13-7：
​

图13-7

运行结束后，会在桌面看到诗词的txt文件。如果出现Filesystem MCP Server不能安装的情况，可选择手动安装：

npx -y @modelcontextprotocol/server-filesystem C:\Users\username\Desktop C:\Users\username\Downloads

13.6.3 测试天气服务器

熟悉Claude for Desktop的操作后，我们就可以开始测试天气服务器。由于Claude for Desktop暂不支持Linux平台，Linux用户可转至13.7节的构建客户端教程，学习如何构建连接刚创建服务器的MCP客户端，以便完成测试。

1. 配置Claude for Desktop

首先，在确保已安装Claude for Desktop情况下，为其配置要使用的MCP天气服务器。操作步骤如下：

1. 使用文本编辑器打开配置文件：Windows: %APPDATA%\Claude\claude_desktop_config.json。若文件不存在，请新建该配置文件。若已安装VS Code，可通过以下命令操作：

code $env:AppData\Claude\claude_desktop_config.json

2. 在mcpServers配置项中添加服务器信息。请注意：只有当至少正确配置一个服务器后，Claude for Desktop才会显示MCP UI元素。本示例中，我们将按以下格式添加天气服务器配置：

{"mcpServers": {"weather": {"command": "node","args": ["C:\\PATH\\TO\\PARENT\\FOLDER\\weather\\build\\index.js"]}}
}

该配置告诉Claude for Desktop，存在一个名为"weather"的MCP服务器，通过执行命令：node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js启动该服务器。完成配置后保存，重新启动Claude for Desktop应用程序并等待几分钟。

2. 工具指令测试

请按以下步骤验证Claude for Desktop是否成功识别天气服务器暴露的两个工具：

1. 在输入界面左下角查找滑块图标“Search and tools”，单击图标后选择“weather”，应看到两个已注册工具，如图13-8：
   图13-8

若服务器未被识别，请仔细查看操作步骤或日志记录。

2. 若工具设置图标已显示，即可通过以下指令测试服务：
   • What’s the weather in Sacramento?
   • What are the active weather alerts in Texas?

由于这里使用的是美国国家气象局接口，因此查询仅适用于美国各地。在经过一些授权后，查询结果如图13-9：

图13-9
可以看到，Claude成功调用工具get-forecast预测了Sacramento的天气并给除出行建议。

13.6.4 MCP服务器示例大全

MCP服务器示例大全是MCP官方的参考服务器实现集合，同时包含其他提供商和社区构建的服务器资源及相关参考资料。示例代码库由Anthropic管理，但是由社区和厂商共同构建。

1. 实现方案与示例服务器列表

本节展示各种MCP服务器，这些服务器体现了MCP协议的功能性和多样性，使大语言模型能够安全地访问各类工具和数据源。每个MCP服务器通常采用以下任一语言的SDK实现：

• C# MCP SDK
• Java MCP SDK
• Kotlin MCP SDK
• Python MCP SDK
• TypeScript MCP SDK

注：列表按字母顺序排列，以最小化新增条目时的合并冲突。

官方参考服务器展示了MCP核心功能和SDK使用方法，当前维护版本的服务器有：

• Everything：集成提示词、资源与工具的参考/测试服务器。
• Fetch：为高效使用LLM设计的网页内容获取与转换工具。
• Filesystem：支持可配置、访问、控制的安全文件操作系统。
• Git：提供Git仓库读取、搜索与操作功能的工具集。
• Memory：基于知识图谱的持久化记忆系统。
• Sequential Thinking：通过思维序列实现动态反思式解决问题。
• Time：时间与时区转换功能模块。

归档版本，不再积极维护，仅作为历史参考提供，完整代码已迁移至servers-archived仓库。如需要某工具的维护版，可在第三方服务器的对应提供商列表中查找。归档服务器如下：

• AWS KB Retrieval：通过Bedrock Agent Runtime访问AWS知识库。
• Brave Search：基于Brave’s Search API的网络与本地搜索。
• EverArt：支持多种模型的AI图像生成系统。
• GitHub：仓库管理、文件操作及GitHub API集成。
• GitLab：支持项目管理的GitLab API集成。
• Google Drive：Google Drive文件访问与搜索功能。
• Google Maps：定位服务、路线导航与地点详情查询。
• PostgreSQL：带模式检查功能的数据库只读访问。
• Puppeteer：浏览器自动化与网页抓取工具。
• Redis：Redis键值存储交互接口。
• Sentry：Sentry.io问题检索与分析模块。
• Slack：频道管理与消息功能集成。
• SQLite：数据库交互与业务智能化功能。

此外，还有上百种的第三方服务器，包括厂商官方整合版和社区版，这里不再列举，感兴趣的读者请参阅：MCP Servers - Third-Party Servers。

2. 框架与资源

下面这些高级框架，可以更容易地构建MCP服务器或客户端，此外还有一些附加的MCP资源。这里只简单列举常用或重要的框架与资源，更多更详细信息请参考：MCP Servers - Frameworks & Resources。

服务器框架目前有十五个，挑选关注度较高的四种，简单列举如下：

• EasyMCP：当前在测试阶段，EasyMCP是通过TypeScript创建模型MCP服务器的最简方案。它将底层通信、格式编排及其他样板定义隐藏在简洁的声明之后，既可仅定义基础要素快速启动，也能创建复杂的资源、模板、工具及提示等高级组件。
• FastMCP：用于构建MCP服务器的TypeScript框架，能够处理客户端会话。有关Python实现，请参阅：Python - FastMCP。FastMCP基于官方SDK构建，通过提供一套标准化框架消除了底层复杂性，自动处理所有样板代码，为常见任务提供简洁直观的API，让开发者专注于MCP核心功能。
• MCP-Framework ：优雅高效的TypeScript构建和管理MCP服务器方案，专为与MCP客户端（如Claude for Desktop）协同工作而设计。可通过CLI工具mcp create app快速创建项目，核心优势包括开箱即用的架构、声明式抽象层及极简开发体验。
• MCP Plexus：现代AI安全多租户MCP服务器框架，可轻松构建强大、可扩展且安全的MCP应用。MCP Plexus是基于jlowin/fastmcp（FastMCP 2.7）库的Python框架，专为开发者设计，支持通过OAuth 2.1与外部服务安全集成，并管理工具的API密钥访问。它允许定义独立隔离且持久化的租户环境，每个租户可向大语言模型和AI代理提供定制化的工具、资源和提示集。

客户端框架较少，目前只有四个，挑选两个列举如下：

• MCP-Agent ：LastMile AI推出的轻量级可组合框架，可基于MCP构建智能体，是构建健壮智能体应用的最简方案。Anthropic为AI应用开发者公布了两项基础性更新：MCP和BEA（Building Effective Agents，构建高效智能体）。mcp-agent将这两个基础部分放入一个AI应用程序框架中，可自动管理MCP服务器连接的生命周期，完全实现BEA的所有模式，并支持智能体自由组合串联。同时集成OpenAI群蜂（Swarm）模式（兼容任意模型），支持跨模型多智能体编排。与MCP协议相同，本项目处于早期发展阶段。
  MCP CLI Client ：通过MCP实现大语言模型与外部工具交互的命令行宿主程序。当前支持以下模型平台：OpenAI、Azure、DeepSeek与Ollama等。

MCP附加资源目前有三十七个，挑选三个列举如下：

• AiMCP：由Hekmon打造的MCP客户端与服务集合，帮助开发者快速定位合适的MCP工具。其作为MCP工具与服务的核心枢纽（hub），提供MCP客户端的多平台支持，精选MCP服务器解决方案，是工具发现与集成的一站式平台。
• MCP-Get：MCP服务器命令行管理工具，可以发现、安装、更新及移除MCP服务包，使Claude等大语言模型能够与外部服务、数据库和API进行交互，包括GitHub、Slack、Brave Search等平台及各类数据库，为LLM应用提供无缝的外部服务接入能力。
• ToolHive ：是简化MCP服务器发现、部署和管理的轻量级工具，单条命令即可在锁定隔离容器中启动任何MCP服务器，通过容器化技术确保易用性、一致性和安全性。CLI工具支持本地开发，而Kubernetes Operator满足生产环境扩展需求。ToolHive由StacklokLabs开发，可自动配置GitHub Copilot、Cursor等主流客户端。

3. 使用仓库中的MCP服务器

基于TypeScript的服务器可直接通过npx命令运行，例如，以下命令将启动Memory服务器：

npx -y @modelcontextprotocol/server-memory

本仓库中的Python服务器可直接使用uvx或pip运行，推荐使用uvx以获得更简便的安装和使用体验。例如，以下命令将启动Git服务器：

# Using uvx
uvx mcp-server-git# Using pip
pip install mcp-server-git
python -m mcp_server_git

配置Claude集成。要在Claude中使用MCP服务器，请将其添加至配置文件：

{"mcpServers": {"memory": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-memory"]},"github": {"command": "npx","args": ["-y", "@modelcontextprotocol/server-github"],"env": {"GITHUB_PERSONAL_ACCESS_TOKEN": "<YOUR_TOKEN>"}},"git": {"command": "uvx","args": ["mcp-server-git", "--repository", "path/to/git/repo"]}}
}

读者可访问官方的的GitHub论坛，与MCP社区互动。

参考文献

1. Python开发人员，请不要低估TypeScript！
2. TypeScript“杀疯了”！60% 到 70%YC 创企用它构建 AI Agent，超越 Python 有戏了？
3. NPM vs. NPX，傻傻分不清楚
4. uv
5. Python 包管理工具核心指令uvx解析
6. MCP Introduction