服务器开发

开始构建您自己的服务器，以便在 Claude for Desktop 和其他客户端中使用。

在本教程中，我们将构建一个简单的 MCP 天气服务器并将其连接到主机 Claude for Desktop。我们将从基本设置开始，然后进入更复杂的使用案例。

一、我们将构建什么

许多 LLM（包括 Claude）目前无法获取预报和恶劣天气警报。让我们使用 MCP 来解决这个问题！

我们将构建一个公开两个工具的服务器：和 .然后，我们将服务器连接到 MCP 主机（在本例中为 Claude for Desktop）：get-alerts``get-forecast

服务器可以被任何客户端连接。为了简单起见，我们在这里选择了 Claude for Desktop，但我们也在此处提供了有关构建您自己的客户端的指南以及其他客户端的列表。

二、核心 MCP 概念

《模型上下文协议中文网》附注：服务端只有三个概念

MCP 服务器可以提供三种主要类型的功能：

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

让我们开始构建我们的天气服务器吧！您可以在此处找到我们将要构建的内容的完整代码。

三、必备知识

本快速入门假定您熟悉：

• Python
• 像 Claude 这样的LLM

四、系统要求

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

五、设置环境

首先，让我们安装并设置我们的 Python 项目和环境：uv

## macOS或者linux
curl -LsSf https://astral.sh/uv/install.sh | sh
## windows
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

确保之后重新启动终端以确保获取该命令。uv

现在，让我们创建并设置我们的项目：

# 创建一个新的目录用于我们的项目
uv init weather
cd weather

# 创建虚拟环境并激活
uv venv
source .venv/bin/activate

# 安装依赖
uv add "mcp[cli]" httpx

# 创建服务器文件
touch weather.py

现在让我们开始构建您的服务器。

六、构建您的服务器

1、导入包并设置实例

将这些添加到顶部 ：weather.py

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# 初始化 FastMCP 服务器
mcp = FastMCP("weather")

# 常量定义
NWS_API_BASE = "https://api.weather.gov"  # 国家气象局 API 基础 URL
USER_AGENT = "weather-app/1.0"  # 自定义 User-Agent，用于请求标识

FastMCP 类使用 Python 类型提示和文档字符串自动生成工具定义，从而轻松创建和维护 MCP 工具。

2、帮助程序函数

接下来，让我们添加用于查询和格式化 National Weather Service API 中的数据的帮助程序函数：

async def make_nws_request(url: str) -> dict[str, Any] | None:
    """向 NWS（国家气象局）API 发送请求，并进行错误处理。"""
    headers = {
        "User-Agent": USER_AGENT,  # 自定义 User-Agent 以标识请求来源
        "Accept": "application/geo+json"  # 指定接受的响应格式为 GeoJSON
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)  # 发送 GET 请求，超时时间为 30 秒
            response.raise_for_status()  # 如果响应状态码指示错误，则抛出异常
            return response.json()  # 返回解析后的 JSON 数据
        except Exception:
            return None  # 请求失败时返回 None

def format_alert(feature: dict) -> str:
    """将气象警报信息格式化为可读字符串。"""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}  # 事件名称，例如飓风、暴风雪等
Area: {props.get('areaDesc', 'Unknown')}  # 受影响区域描述
Severity: {props.get('severity', 'Unknown')}  # 严重程度，例如 Extreme、Severe、Moderate
Description: {props.get('description', 'No description available')}  # 详细描述
Instructions: {props.get('instruction', 'No specific instructions provided')}  # 指导性说明，例如避难建议
"""

3、实现工具执行

工具执行处理程序负责实际执行每个工具的逻辑。让我们添加它：

@mcp.tool()
async def get_alerts(state: str) -> str:
    """获取指定美国州的天气警报信息。

    参数:
        state: 两位字母的美国州代码（例如 CA, NY）。
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"  # 构造 NWS API 请求 URL
    data = await make_nws_request(url)  # 发送请求获取数据

    if not data or "features" not in data:  # 检查是否成功获取数据
        return "无法获取警报信息，或者该州当前没有警报。"

    if not data["features"]:  # 如果 features 为空，则表示没有活跃的警报
        return "该州目前没有活跃的天气警报。"

    alerts = [format_alert(feature) for feature in data["features"]]  # 格式化所有警报信息
    return "\n---\n".join(alerts)  # 以分隔线拼接多个警报信息


@mcp.tool()
async def get_forecast(latitude: float, longitude: float) -> str:
    """获取指定经纬度位置的天气预报。

    参数:
        latitude: 位置的纬度
        longitude: 位置的经度
    """
    # 第一步：获取预报数据的网格端点
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"  # 构造查询网格的 URL
    points_data = await make_nws_request(points_url)  # 发送请求

    if not points_data:  # 如果未能获取数据
        return "无法获取该位置的天气预报数据。"

    # 从返回的数据中提取预报 URL
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)  # 获取详细的天气预报数据

    if not forecast_data:  # 如果预报数据为空
        return "无法获取详细的天气预报。"

    # 提取天气预报周期数据，并格式化
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # 仅显示最近 5 个预报时段
        forecast = f"""
{period['name']}:
温度: {period['temperature']}°{period['temperatureUnit']}
风速: {period['windSpeed']} {period['windDirection']}
天气情况: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)  # 以分隔线拼接多个天气预报

4、运行服务器

最后，让我们初始化并运行服务器：

if __name__ == "__main__":
    # 初始化并启动服务器
    mcp.run(transport='stdio')

您的服务器已完成！运行 以确认一切正常。uv run weather.py

现在，让我们从现有的 MCP 主机 Claude for Desktop 测试您的服务器。

七、使用 Claude for Desktop 测试您的服务器

Claude for Desktop 在 Linux 上尚不可用。Linux 用户可以继续 构建客户端 教程来构建连接到我们刚刚构建的服务器的 MCP 客户端。

1、配置

首先，确保您已安装 Claude for Desktop。您可以安装最新版本 这里。如果您已经拥有 Claude for Desktop，请确保它已更新到最新版本。

我们需要为您想要使用的任何 MCP 服务器配置 Claude for Desktop。为此，请在文本编辑器中打开 Claude for Desktop App 配置。如果文件不存在，请确保创建该文件。~/Library/Application Support/Claude/claude_desktop_config.json

例如，如果您安装了 VS Code：

## MacOS/Linux
code ~/Library/Application\ Support/Claude/claude_desktop_config.json
## windows
code $env:AppData\Claude\claude_desktop_config.json

然后，您将在密钥中添加您的服务器。只有当至少一个服务器配置正确时，MCP UI 元素才会显示在 Claude for Desktop 中。mcpServers

在本例中，我们将添加单个 weather 服务器，如下所示：

• MacOS/Linux

{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "/ABSOLUTE/PATH/TO/PARENT/FOLDER/weather",
                "run",
                "weather.py"
            ]
        }
    }
}

windows

主要是路径斜杠不同

{
    "mcpServers": {
        "weather": {
            "command": "uv",
            "args": [
                "--directory",
                "C:\\ABSOLUTE\\PATH\\TO\\PARENT\\FOLDER\\weather",
                "run",
                "weather.py"
            ]
        }
    }
}

这告诉 Claude for Desktop：

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

保存文件，然后重新启动 Claude for Desktop。

2、使用命令进行测试

让我们确保 Claude for Desktop 选择了我们在服务器中公开的两个工具。您可以通过查找锤子图标来执行此作：weather

单击锤子图标后，您应该会看到列出了两个工具：

如果 Claude for Desktop 未选取您的服务器，请继续执行故障排除部分以获取调试提示。

如果显示锤子图标，您现在可以通过在 Claude for Desktop 中运行以下命令来测试您的服务器：

• 萨克拉门托的天气怎么样？
• 德克萨斯州有哪些活跃的天气警报？

由于这是美国国家气象服务，因此查询仅适用于美国位置。

3、幕后发生了什么

当您提出问题时：

1. 客户将您的问题发送给 Claude
2. Claude 分析了可用的工具并决定使用哪一个
3. 客户端通过 MCP 服务器执行所选工具
4. 结果将发送回给 Claude
5. Claude 制定自然语言响应
6. 响应将向您显示！