构建MCP服务器教程

构建MCP服务器教程在本教程中，我们将构建一个简单的MCP天气服务器并将其连接到主机Claude for Desktop。我们将要构建什么我们将构建一个暴露两个工具的服务器：get_alerts和get_forecast。然后我们将服务器连接到MCP主机（在本例中是Claude for Desktop）：核心MCP概念MCP服务器可以提供三种主要类型的功能：

1.资源：客户端可以读取的文件类数据（如API响应或文件内容）
2.工具：LLM可以调用的函数（需要用户批准）
3.提示：预编写模板，帮助用户完成特定任务

本教程主要关注工具。让我们开始构建我们的天气服务器！您可以在这里找到我们要构建的完整代码。先决条件知识本快速入门假设您熟悉：

• Python
• 像Claude这样的LLM

MCP服务器中的日志记录在实现MCP服务器时，请注意如何处理日志记录：对于基于STDIO的服务器：永远不要写入标准输出（stdout）。这包括：

• Python中的print()语句
• JavaScript中的console.log()
• Go中的fmt.Println()
• 其他语言中的类似stdout函数

写入stdout会破坏JSON-RPC消息并使您的服务器崩溃。对于基于HTTP的服务器：标准输出日志记录没有问题，因为它不会干扰HTTP响应。最佳实践

1. 使用将日志写入stderr或文件的日志库。

快速示例# ❌ 错误（STDIO）print("Processing request")# ✅ 正确（STDIO）import logginglogging.info("Processing request")

系统要求

• 已安装Python 3.10或更高版本。
• 必须使用Python MCP SDK 1.2.0或更高版本。

设置您的环境首先，让我们安装uv并设置我们的Python项目和环境：确保之后重新启动终端以确保uv命令被识别。现在，让我们创建和设置我们的项目：现在让我们深入了解构建您的服务器。构建您的服务器导入包和设置实例将这些添加到您的weather.py顶部：fromtypingimportAnyimporthttpxfrommcp.server.fastmcpimportFastMCP# 初始化FastMCP服务器mcp = FastMCP("weather")# 常量NWS_API_BASE ="https://api.weather.gov"USER_AGENT ="weather-app/1.0"

FastMCP类使用Python类型提示和文档字符串自动生成工具定义，使得创建和维护MCP工具变得容易。辅助函数接下来，让我们添加用于查询和格式化国家气象局API数据的辅助函数：asyncdefmake_nws_request(url:str) ->dict[str,Any] |None: """向NWS API发出请求并进行适当的错误处理。""" headers = { "User-Agent": USER_AGENT, "Accept":"application/geo+json" } asyncwithhttpx.AsyncClient()asclient: try: response =awaitclient.get(url, headers=headers, timeout=30.0) response.raise_for_status() returnresponse.json() exceptException: returnNonedefformat_alert(feature:dict) ->str: """将警报特征格式化为可读字符串。""" props = feature["properties"] returnf"""事件:{props.get('event','未知')}区域:{props.get('areaDesc','未知')}严重程度:{props.get('severity','未知')}描述:{props.get('description','无可用描述')}指示:{props.get('instruction','无特定指示')}"""

实现工具执行工具执行处理程序负责实际执行每个工具的逻辑。让我们添加它：@mcp.tool()asyncdefget_alerts(state:str) ->str: """获取美国州的天气警报。参数: state: 两字母美国州代码（例如 CA, NY） """ url =f"{NWS_API_BASE}/alerts/active/area/{state}" data =awaitmake_nws_request(url) ifnotdataor"features"notindata: return"无法获取警报或未找到警报。" ifnotdata["features"]: return"此州无活动警报。" alerts = [format_alert(feature)forfeatureindata["features"]] return" --- ".join(alerts)@mcp.tool()asyncdefget_forecast(latitude:float, longitude:float) ->str: """获取位置的天气预报。参数: latitude: 位置的纬度 longitude: 位置的经度 """ # 首先获取预报网格端点 points_url =f"{NWS_API_BASE}/points/{latitude},{longitude}" points_data =awaitmake_nws_request(points_url) ifnotpoints_data: return"无法获取此位置的预报数据。" # 从点响应中获取预报URL forecast_url = points_data["properties"]["forecast"] forecast_data =awaitmake_nws_request(forecast_url) ifnotforecast_data: return"无法获取详细预报。" # 将时间段格式化为可读的预报 periods = forecast_data["properties"]["periods"] forecasts = [] forperiodinperiods[:5]: # 仅显示接下来的5个时间段 forecast =f"""{period['name']}:温度:{period['temperature']}°{period['temperatureUnit']}风力:{period['windSpeed']}{period['windDirection']}预报:{period['detailedForecast']}""" forecasts.append(forecast) return" --- ".join(forecasts)

运行服务器最后，让我们初始化并运行服务器：if__name__ =="__main__": # 初始化并运行服务器 mcp.run(transport='stdio')

您的服务器已完成！运行uv run weather.py启动MCP服务器，该服务器将监听来自MCP主机的消息。现在让我们从现有的MCP主机Claude for Desktop测试您的服务器。使用Claude for Desktop测试您的服务器首先，确保您已安装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：

1. 有一个名为”weather”的MCP服务器
2. 通过运行uv --directory /ABSOLUTE/PATH/TO/PARENT/FOLDER/weather run weather.py来启动它

保存文件，然后重新启动Claude for Desktop。使用命令测试让我们确保Claude for Desktop能够识别我们在weather服务器中暴露的两个工具。您可以通过查找”搜索和工具”图标来实现这一点。点击滑块图标后，您应该看到列出的两个工具：如果Claude for Desktop没有识别到您的服务器，请前往故障排除部分获取调试提示。如果工具设置图标已显示，您现在可以通过在Claude for Desktop中运行以下命令来测试您的服务器：