这是用户在 2025-4-10 17:34 为 https://modelcontextprotocol.io/quickstart/server#claude-for-desktop-integration-issues 保存的双语快照页面,由 沉浸式翻译 提供双语支持。了解如何保存?

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

我们要构建的内容

许多 LLMs 目前无法获取天气预报和恶劣天气警报。让我们使用 MCP 来解决这个问题!

我们将构建一个服务器,提供两个工具:get-alertsget-forecast。然后,我们将服务器连接到 MCP 主机(在这种情况下,是桌面版的 Claude):

服务器可以连接到任何客户端。我们在这里选择了桌面版的 Claude 以简化操作,但我们也有关于构建您自己的客户端的指南以及其他客户端的列表

核心 MCP 概念

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

  1. 资源 : 类似文件的数据,可以被客户端读取(如 API 响应或文件内容)
  2. 工具 : 可以被LLM调用的功能(需用户批准)
  3. 提示 : 帮助用户完成特定任务的预写模板

本教程将主要关注工具。

让我们开始构建我们的天气服务器吧! 你可以在这里找到我们将要构建的完整代码。

前提知识

本快速入门假设您熟悉以下内容:

  • Python
  • LLMs like Claude

系统要求

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

设置你的环境

首先,我们来安装 uv 并设置 Python 项目和环境:

curl -LsSf https://astral.sh/uv/install.sh | sh

确保之后重启您的终端,以保证 uv 命令能够被识别。

现在,让我们创建并设置我们的项目:

# Create a new directory for our project
uv init weather
cd weather

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx

# Create our server file
touch weather.py

现在让我们深入构建你的服务器。

构建你的服务器

导入包并设置实例

将这些添加到你的 weather.py 文件的顶部:

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

# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants
NWS_API_BASE = "https://api.weather.gov"
USER_AGENT = "weather-app/1.0"

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

辅助函数

接下来,让我们添加用于查询和格式化来自 National Weather Service API 的数据的辅助函数:

async def make_nws_request(url: str) -> dict[str, Any] | None:
    """Make a request to the NWS API with proper error handling."""
    headers = {
        "User-Agent": USER_AGENT,
        "Accept": "application/geo+json"
    }
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, headers=headers, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None

def format_alert(feature: dict) -> str:
    """Format an alert feature into a readable string."""
    props = feature["properties"]
    return f"""
Event: {props.get('event', 'Unknown')}
Area: {props.get('areaDesc', 'Unknown')}
Severity: {props.get('severity', 'Unknown')}
Description: {props.get('description', 'No description available')}
Instructions: {props.get('instruction', 'No specific instructions provided')}
"""

实现工具执行

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

@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get weather alerts for a US state.

    Args:
        state: Two-letter US state code (e.g. CA, NY)
    """
    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
    data = await make_nws_request(url)

    if not data or "features" not in data:
        return "Unable to fetch alerts or no alerts found."

    if not data["features"]:
        return "No active alerts for this state."

    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:
    """Get weather forecast for a location.

    Args:
        latitude: Latitude of the location
        longitude: Longitude of the location
    """
    # First get the forecast grid endpoint
    points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}"
    points_data = await make_nws_request(points_url)

    if not points_data:
        return "Unable to fetch forecast data for this location."

    # Get the forecast URL from the points response
    forecast_url = points_data["properties"]["forecast"]
    forecast_data = await make_nws_request(forecast_url)

    if not forecast_data:
        return "Unable to fetch detailed forecast."

    # Format the periods into a readable forecast
    periods = forecast_data["properties"]["periods"]
    forecasts = []
    for period in periods[:5]:  # Only show next 5 periods
        forecast = f"""
{period['name']}:
Temperature: {period['temperature']}°{period['temperatureUnit']}
Wind: {period['windSpeed']} {period['windDirection']}
Forecast: {period['detailedForecast']}
"""
        forecasts.append(forecast)

    return "\n---\n".join(forecasts)

运行服务器

最后,我们来初始化并运行服务器:

if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='stdio')

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

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

使用 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

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

然后你将把你的服务器添加到 mcpServers 键中。只有当至少一个服务器配置正确时,Claude for Desktop 中的 MCP 界面元素才会显示。

在这种情况下,我们将添加单个天气服务器,如下所示:

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

您可能需要在 command 字段中填入 uv 可执行文件的完整路径。您可以通过在 MacOS/Linux 上运行 which uv 或在 Windows 上运行 where uv 来获取此路径。

确保你传入的是服务器的绝对路径。

这告诉 Claude for Desktop:

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

保存文件,并重启 Claude for Desktop

使用命令进行测试

确保桌面版 Claude 识别到我们在 weather 服务器中公开的两个工具。您可以通过查找锤子 图标来完成此操作:

点击锤子图标后,你应该会看到列出两个工具:

如果你的服务器没有被 Claude for Desktop 识别,请前往故障排除部分以获取调试建议。

如果锤子图标已经出现,您现在可以通过在 Claude for Desktop 中运行以下命令来测试您的服务器:

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

由于这是美国国家气象服务,查询仅适用于美国地区。

“在背后发生了什么”

当你提出一个问题时:

  1. 客户端将你的问题发送给了 Claude
  2. Claude 分析可用的工具并决定使用哪一个(些)
  3. 客户端通过 MCP 服务器执行选定的工具
  4. 结果被发送回 Claude
  5. 克劳德生成一个自然语言响应
  6. 响应已显示给您!

故障排查

要进行更高级的故障排除,请查看我们的指南:Debugging MCP

下一步

这页是否有帮助?