学习如何构建自己的服务器,以便在 Claude for Desktop 和其他客户端中使用。
在本教程中,我们将构建一个简单的 MCP 天气服务器,并将其连接到宿主环境 Claude for Desktop。我们将从基本设置开始,然后逐步过渡到更复杂的用例。
目前许多 LLM(包括 Claude)都没有获取天气预报和严重天气警报的能力。让我们使用 MCP 来解决这个问题!
我们将构建一个暴露两个工具的服务器:get-alerts
和 get-forecast
。然后我们将把服务器连接到一个 MCP 宿主环境(在本例中是 Claude for Desktop):
为什么选择 Claude for Desktop 而不是 Claude.ai?
因为服务器是本地运行的,MCP 目前只支持桌面宿主环境。远程宿主环境正在积极开发中。
MCP 服务器可以提供三种主要类型的功能:
本教程将主要关注工具的使用。
让我们开始构建我们的天气服务器!你可以在这里找到我们将要构建的完整代码。
本快速入门假设你熟悉:
首先,让我们安装 uv
并设置 Python 项目和环境:
安装完成后,请确保重启终端以确保 uv
命令可以被正常使用。
现在,让我们创建并设置我们的项目:
现在让我们深入构建服务器。
将以下内容添加到 weather.py
的顶部:
FastMCP 类使用 Python 类型提示和文档字符串自动生成工具定义,使创建和维护 MCP 工具变得容易。
接下来,让我们添加用于查询和格式化国家气象服务 API 数据的辅助函数:
工具执行处理器负责实际执行每个工具的逻辑。让我们添加它:
最后,让我们初始化并运行服务器:
你的服务器已经完成!运行 uv run weather.py
来确认一切正常工作。
现在让我们从一个现有的 MCP 宿主环境 Claude for Desktop 测试你的服务器。
Claude for Desktop 目前尚未在 Linux 上提供。Linux 用户可以继续学习构建客户端教程,以构建一个连接到我们刚刚构建的服务器的 MCP 客户端。
首先,确保你已安装 Claude for Desktop。你可以在这里安装最新版本。如果你已经安装了 Claude for Desktop,请确保它已更新到最新版本。
我们需要为你想要使用的 MCP 服务器配置 Claude for Desktop。为此,请在文本编辑器中打开你的 Claude for Desktop 应用程序配置文件,路径为 ~/Library/Application Support/Claude/claude_desktop_config.json
。如果该文件不存在,请创建它。
例如,如果你安装了 VS Code:
然后你需要在 mcpServers
键中添加你的服务器。只有在至少正确配置了一个服务器的情况下,MCP UI 元素才会在 Claude for Desktop 中显示。
在这种情况下,我们将添加我们的单个天气服务器,如下所示:
你可能需要在 command
字段中填写 uv
可执行文件的完整路径。你可以通过在 MacOS/Linux 上运行 which uv
或在 Windows 上运行 where uv
来获取。
确保你传入服务器的绝对路径。
这告诉 Claude for Desktop:
uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather
来启动它保存文件,然后重启 Claude for Desktop。
让我们开始构建我们的天气服务器!你可以在这里找到我们将要构建的完整代码。
本快速入门假设你熟悉:
首先,让我们安装 uv
并设置 Python 项目和环境:
安装完成后,请确保重启终端以确保 uv
命令可以被正常使用。
现在,让我们创建并设置我们的项目:
现在让我们深入构建服务器。
将以下内容添加到 weather.py
的顶部:
FastMCP 类使用 Python 类型提示和文档字符串自动生成工具定义,使创建和维护 MCP 工具变得容易。
接下来,让我们添加用于查询和格式化国家气象服务 API 数据的辅助函数:
工具执行处理器负责实际执行每个工具的逻辑。让我们添加它:
最后,让我们初始化并运行服务器:
你的服务器已经完成!运行 uv run weather.py
来确认一切正常工作。
现在让我们从一个现有的 MCP 宿主环境 Claude for Desktop 测试你的服务器。
Claude for Desktop 目前尚未在 Linux 上提供。Linux 用户可以继续学习构建客户端教程,以构建一个连接到我们刚刚构建的服务器的 MCP 客户端。
首先,确保你已安装 Claude for Desktop。你可以在这里安装最新版本。如果你已经安装了 Claude for Desktop,请确保它已更新到最新版本。
我们需要为你想要使用的 MCP 服务器配置 Claude for Desktop。为此,请在文本编辑器中打开你的 Claude for Desktop 应用程序配置文件,路径为 ~/Library/Application Support/Claude/claude_desktop_config.json
。如果该文件不存在,请创建它。
例如,如果你安装了 VS Code:
然后你需要在 mcpServers
键中添加你的服务器。只有在至少正确配置了一个服务器的情况下,MCP UI 元素才会在 Claude for Desktop 中显示。
在这种情况下,我们将添加我们的单个天气服务器,如下所示:
你可能需要在 command
字段中填写 uv
可执行文件的完整路径。你可以通过在 MacOS/Linux 上运行 which uv
或在 Windows 上运行 where uv
来获取。
确保你传入服务器的绝对路径。
这告诉 Claude for Desktop:
uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather
来启动它保存文件,然后重启 Claude for Desktop。
让我们开始构建我们的天气服务器!你可以在这里找到我们将要构建的完整代码。
本快速入门假设你熟悉:
对于 TypeScript,请确保你已安装最新版本的 Node。
首先,如果你还没有安装 Node.js 和 npm,请先安装。你可以从 nodejs.org 下载。 验证你的 Node.js 安装:
对于本教程,你需要 Node.js 16 或更高版本。
现在,让我们创建并设置我们的项目:
更新你的 package.json 以添加 type: “module” 和构建脚本:
在项目根目录创建 tsconfig.json
:
现在让我们开始构建服务器。
将以下内容添加到 src/index.ts
的顶部:
接下来,让我们添加用于查询和格式化国家气象服务 API 数据的辅助函数:
工具执行处理器负责实际执行每个工具的逻辑。让我们添加它:
最后,实现运行服务器的主函数:
确保运行 npm run build
来构建你的服务器!这是让你的服务器能够连接的一个非常重要的步骤。
现在让我们从一个现有的 MCP 宿主环境 Claude for Desktop 来测试你的服务器。
Claude for Desktop 目前尚未在 Linux 上提供。Linux 用户可以继续阅读构建客户端教程,构建一个可以连接到我们刚刚构建的服务器的 MCP 客户端。
首先,确保你已安装 Claude for Desktop。你可以在这里安装最新版本。如果你已经安装了 Claude for Desktop,请确保更新到最新版本。
我们需要为你想要使用的 MCP 服务器配置 Claude for Desktop。要做到这一点,请在文本编辑器中打开你的 Claude for Desktop 应用程序配置文件,路径为 ~/Library/Application Support/Claude/claude_desktop_config.json
。如果该文件不存在,请创建它。
例如,如果你安装了 VS Code:
然后你需要在 mcpServers
键中添加你的服务器。只有当至少有一个服务器被正确配置时,MCP UI 元素才会在 Claude for Desktop 中显示。
在这种情况下,我们将添加我们的单个天气服务器,如下所示:
这告诉Claude for Desktop:
node /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather/build/index.js
来启动它保存文件,然后重启Claude for Desktop。
这是一个基于Spring AI MCP自动配置和启动器的快速入门演示。 要了解如何手动创建同步和异步MCP服务器,请参考Java SDK服务器文档。
让我们开始构建我们的天气服务器! 你可以在这里找到我们将要构建的完整代码。
更多信息,请参见MCP服务器启动器参考文档。 关于手动MCP服务器实现,请参考MCP服务器Java SDK文档。
使用Spring Initizer来引导项目。
你需要添加以下依赖:
然后通过设置应用程序属性来配置你的应用:
服务器配置属性文档列出了所有可用的属性。
现在让我们深入构建你的服务器。
让我们实现一个WeatherService.java,它使用REST客户端从国家气象服务API查询数据:
@Service
注解会在你的应用程序上下文中自动注册服务。
Spring AI的@Tool
注解使创建和维护MCP工具变得容易。
自动配置将自动向MCP服务器注册这些工具。
使用MethodToolCallbackProvider
工具将@Tools
转换为MCP服务器使用的可执行回调。
最后,让我们构建服务器:
这将在target
文件夹中生成一个mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar
文件。
现在让我们从一个现有的MCP宿主环境Claude for Desktop测试你的服务器。
Claude for Desktop目前尚未在Linux上提供。
首先,确保你已安装Claude for Desktop。 你可以在这里安装最新版本。如果你已经安装了Claude for Desktop,请确保它已更新到最新版本。
我们需要为你想要使用的MCP服务器配置Claude for Desktop。
为此,请在文本编辑器中打开你的Claude for Desktop应用程序配置文件,路径为~/Library/Application Support/Claude/claude_desktop_config.json
。
如果该文件不存在,请创建它。
例如,如果你安装了VS Code:
然后你需要在 mcpServers
键中添加你的服务器。只有在至少正确配置了一个服务器的情况下,MCP UI 元素才会在 Claude for Desktop 中显示。
在这种情况下,我们将添加我们的单个天气服务器,如下所示:
确保你传入服务器的绝对路径。
这告诉 Claude for Desktop:
java -jar /ABSOLUTE/PATH/TO/PARENT/FOLDER/mcp-weather-stdio-server-0.0.1-SNAPSHOT.jar
来启动它保存文件,然后重启 Claude for Desktop。
使用 McpClient
连接到服务器:
使用 spring-ai-mcp-client-spring-boot-starter
依赖创建一个新的启动器应用程序:
并设置 spring.ai.mcp.client.stdio.servers-configuration
属性指向你的 claude_desktop_config.json
。
你可以重用现有的 Anthropic Desktop 配置:
当你启动客户端应用程序时,自动配置将从 claude_desktop_config.json 自动创建 MCP 客户端。
更多信息,请参阅 MCP 客户端启动器 参考文档。
starter-webflux-server 演示了如何使用 SSE 传输创建 MCP 服务器。 它展示了如何使用 Spring Boot 的自动配置功能定义和注册 MCP 工具、资源和提示。
让我们确保 Claude for Desktop 能够识别我们在 weather
服务器中暴露的两个工具。你可以通过查找锤子 icon:
点击锤子图标后,你应该能看到列出的两个工具:
如果你的服务器没有被 Claude for Desktop 识别,请查看故障排除部分获取调试提示。
如果锤子图标已经显示,你现在可以在 Claude for Desktop 中运行以下命令来测试你的服务器:
由于这是美国国家气象服务,查询只适用于美国地区。
当你提出问题时:
Claude桌面版集成问题
获取Claude桌面版日志
Claude.app与MCP相关的日志记录在~/Library/Logs/Claude
目录下:
mcp.log
包含有关MCP连接和连接失败的一般日志。mcp-server-SERVERNAME.log
的文件包含指定服务器的错误(stderr)日志。你可以运行以下命令列出最近的日志并实时跟踪新的日志:
服务器未在Claude中显示
claude_desktop_config.json
文件语法工具调用静默失败
如果Claude尝试使用工具但失败:
以上方法都不起作用,我该怎么办?
请参考我们的调试指南获取更好的调试工具和更详细的指导。
天气API问题
错误:无法获取网格点数据
这通常意味着:
解决方法:
错误:[州]没有活动警报
这不是错误 - 这只是意味着该州目前没有天气警报。尝试其他州或在恶劣天气期间检查。
要获取更高级的故障排除方法,请查看我们的MCP调试指南
学习如何构建可以连接到你的服务器的 MCP 客户端
查看我们的官方 MCP 服务器和实现示例库
学习如何有效调试 MCP 服务器和集成
学习如何使用像 Claude 这样的 LLMs 来加速你的 MCP 开发