前置準備

開始前，請確保您已準備好以下項目：

• 已安裝 Python 3.10 或更高版本。
• 基本熟悉 Python 函式與非同步程式碼。
• uv（快速的 Python 套件管理工具） – 使用 curl -LsSf https://astral.sh/uv/install.sh | sh 指令安裝。
• 一個 MCP 客戶端，例如 Claude Desktop（從 claude.ai/download 下載並保持更新）。
• 一個文字編輯器或整合開發環境（IDE）。

無需事先具備 MCP 經驗。我們將建立一個實用的 天氣 MCP 伺服器，讓 AI 能透過國家氣象局（NWS）API 查詢即時的美國天氣警報與預報。

步驟 1：設定環境

建立一個乾淨的專案目錄，並使用 uv 進行初始化：

mkdir weather-mcp-server
cd weather-mcp-server
uv init
uv venv
source .venv/bin/activate  # 在 Windows 上：.venv\Scripts\activate
uv add "mcp[cli]" httpx

這將安裝官方的 MCP Python SDK（FastMCP）以及用於 API 呼叫的 httpx。您的專案現在應包含 pyproject.toml 檔案與虛擬環境。

預期輸出： 新的 .venv 資料夾，以及列在 uv.lock 中的相依套件。

步驟 2：建立 MCP 伺服器程式碼

建立主要檔案：

touch weather.py

將以下完整、可立即執行的程式碼貼到 weather.py 中：

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

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

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

# 輔助函式：安全地呼叫 NWS API
async def make_nws_request(url: str) -> dict[str, Any] | None:
    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

# 將天氣警報格式化，以便 AI 清晰閱讀
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")}
Description: {props.get("description", "No description available")}
Instructions: {props.get("instruction", "No specific instructions provided")}
"""

# 工具 1：取得美國某個州的現行天氣警報
@mcp.tool()
async def get_alerts(state: str) -> str:
    """Get current weather alerts for a U.S. state (e.g., "CA" or "TX")."""
    url = f"{NWS_API_BASE}/alerts/active/area/{state.upper()}"
    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 f"No active alerts for {state.upper()}."
    alerts = [format_alert(f) for f in data["features"]]
    return "\n---\n".join(alerts)

工具 2：取得任意緯度/經度的 5 天預報

@mcp.tool() async def get_forecast(latitude: float, longitude: float) -> str: """取得特定緯度和經度的天氣預報。""" points_url = f"{NWS_API_BASE}/points/{latitude},{longitude}" points_data = await make_nws_request(points_url) if not points_data: return "無法取得此位置的天氣預報數據。" forecast_url = points_data["properties"]["forecast"] forecast_data = await make_nws_request(forecast_url) if not forecast_data: return "無法取得詳細預報。" periods = forecast_data["properties"]["periods"][:5] forecasts = [] for period in periods: forecast = f""" {period["name"]}: 溫度：{period["temperature"]}°{period["temperatureUnit"]} 風速：{period["windSpeed"]} {period["windDirection"]} 預報：{period["detailedForecast"]} """ forecasts.append(forecast) return "\n---\n".join(forecasts)

def main(): mcp.run(transport="stdio")

if name == "main": main()

**關鍵概念說明：**
- `@mcp.tool()` 裝飾器將普通的 async 函數轉換為 AI 能夠發現並呼叫的 MCP 工具。
- 伺服器透過 **stdio**（標準輸入/輸出）運行 — 這是本地 MCP 伺服器的預設方式。
- 所有日誌記錄應輸出到 stderr（FastMCP 會自動處理）。

## 步驟 3：在本地測試伺服器

執行伺服器：

```bash
uv run weather.py

預期輸出： 終端機保持開啟且無輸出（這是 stdio 伺服器的正常現象）。只有當 MCP 客戶端連接時，您才會看到 JSON-RPC 訊息。

請保持此終端機運行，以進行下一步。

步驟 4：將 MCP 伺服器連接至 Claude Desktop

1. 開啟 Claude Desktop。
2. 建立或編輯位於以下位置的設定檔：
   • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json

加入以下確切項目（請將 /ABSOLUTE/PATH/TO/weather-mcp-server 替換為您的實際資料夾路徑）：

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

3. 完全退出 Claude Desktop（macOS 為 Cmd+Q，Windows 為從系統匣關閉），然後重新啟動它。
4. 在 Claude 中，點擊 「Add files, connectors, and more」 → 懸停在 Connectors 上 → 您應該會看到 「weather」 列出。

步驟 5：與 AI 一起使用您的 MCP 伺服器

在 Claude Desktop 中嘗試這些提示：

「德州有哪些活躍的天氣警報？」

• 「給我舊金山的天氣預報（使用緯度 37.77，經度 -122.41）。」
• 「檢查加州的警報，並告訴我是否需要準備任何事項。」

Claude 將自動發現這些工具，第一次使用時會徵求您的同意，然後返回格式化的結果。

預期行為： AI 將在後台呼叫您的工具，並以自然語言顯示答案。

常見問題與疑難排解

• 伺服器未出現在 Claude 中：

  • 再次確認 JSON 格式是否有效（無多餘的逗號）。
  • 在配置中使用絕對路徑。
  • 完全重新啟動 Claude。
  • 檢查日誌：~/Library/Logs/Claude/mcp*.log（macOS）或 Windows 上的等效位置。

• API 錯誤或無資料：

  • NWS API 僅適用於美國境內地點。
  • 請使用兩個字母的州代碼（例如 CA、TX 等）。
  • 座標必須是有效的緯度/經度。

• 「指令未找到」：

  • 確保 uv 已在您的 PATH 中且虛擬環境已啟用。
  • 執行 uv --version 來驗證安裝。

• 逾時或回應緩慢：

  • 如有需要，可在 make_nws_request 中增加逾時設定。
  • NWS 有速率限制——避免在正式環境中頻繁請求。

• 權限問題：

  • 在 macOS 上，請前往系統設定 → 隱私與安全性，授予 Claude Desktop 完整的磁碟存取權限。

後續步驟

• 新增更多工具：使用相同的 @mcp.tool() 模式，建立適用於資料庫、GitHub、Slack 或您自己的 API 的工具。
• 新增資源與提示：使用 mcp.resource() 和 mcp.prompt() 來處理檔案類資料及可重複使用的指令。 -a 遠端部署：切換到 HTTP/SSE 傳輸協定，並在 AWS Lambda、Vercel 或任何伺服器上部署（FastMCP 支援 stateless_http=True）。
• 支援多種語言：嘗試使用官方的 TypeScript、Go 或 Rust SDK 以實現相同的功能。
• 分享您的伺服器：將倉儲發佈出去，讓其他人可以透過 npx 或 Docker 來新增它。

您現在已擁有一個功能完整的 MCP 伺服器，任何相容的 AI 用戶端皆可使用。立即開始試驗、擴充工具，並著手建構強大的 AI 整合吧！