mcp-weather

mcp-weather

By erhwenkuo GitHub

一個給 AI Agent 使用的 MCP Server 範例，用來取得美國各州的天氣預報與警示資訊

Overview

what is mcp-weather?

mcp-weather is an MCP server example designed for AI agents to retrieve weather forecasts and alerts for various states in the USA.

how to use mcp-weather?

To use mcp-weather, set up the server using the provided commands, and connect to it using the MCP inspector tool to access weather data.

key features of mcp-weather?

  • Provides real-time weather forecasts and alerts.
  • Supports SSE (Server-Sent Events) for efficient data streaming.
  • Allows connection from AI agents for dynamic weather updates.

use cases of mcp-weather?

  1. AI agents retrieving weather data for decision-making.
  2. Applications needing real-time weather alerts for users.
  3. Integration with other services requiring weather information.

FAQ from mcp-weather?

  • What is SSE and why is it used?

SSE allows the server to push updates to clients in real-time, making it suitable for cloud-native applications.

  • How do I install and run mcp-weather?

Follow the installation instructions provided in the documentation, including setting up the environment and running the server.

  • Can I use mcp-weather for any state in the USA?

Yes! You can retrieve weather data for any state by specifying the state code.

Content

mcp-weather

一個給 AI Agent 使用的 MCP Server 範例，用來取得美國各州的天氣預報與警示資訊。

目的

這個 mcp server 示範了基於 SSE 的 MCP 伺服器和使用其中工具的獨立 MCP 用戶端的工作模式。

運行環境

本專案使用 uv 來管理相關的依賴與 python 的運行環境, 如果尚未安裝 uv 可依照官網的安裝指示來安裝。

接下來的相關命令都是在 Ubuntu 24.04 的環境下執行的, 其它作業系統的操作請自行修改:

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

下載源碼:

$ git clone https://github.com/erhwenkuo/mcp-weather.git

$ cd mcp-weather

$ uv sync

運行服務

使用 uv 來啟動:

$ uv run server

INFO:     Started server process [15784]
INFO:     Waiting for application startup.
INFO:     Application startup complete.
INFO:     Uvicorn running on http://0.0.0.0:8080 (Press CTRL+C to quit)

使用 Docker 來啟動

首先構建 Docker image:

$ docker build -t mcp-weather .

啟動 mcp-weather:

$ docker run -d -p 5488:5488 mcp-weather

驗證結果

首先安裝 nodejs:

# Download and install nvm:
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.2/install.sh | bash

# in lieu of restarting the shell
\. "$HOME/.nvm/nvm.sh"

# Download and install Node.js:
nvm install 22

# Verify the Node.js version:
node -v # Should print "v22.14.0".
nvm current # Should print "v22.14.0".

# Verify npm version:
npm -v # Should print "10.9.2".

接著啟動 mcp inspector:

$ npx @modelcontextprotocol/inspector

Starting MCP inspector...
Proxy server listening on port 3000

🔍 MCP Inspector is up and running at http://localhost:5173 🚀

使用瀏覽器打開 http://localhost:5173, 然後進行下列的動作:

  1. 在 Transport Type 選擇 SSE
  2. 在 URL 鍵入 mcp server 的位址與端口, http://localhost:5488/sse
  3. 點擊 Connect, 如果有看到狀態是 "Connected" 代表己經成功連線到 mcp-weather 服務了
  4. 點擊上方的 "Tools" Tab
  5. 點擊 "List Tools" 按鈕之後會看到有兩個工具:
    • get_alerts
    • get_forecast
  6. 點擊 get_alerts 之後在右側會出現這個工具的說明與參數, 在 state 的輸入欄中鍵入 "CA" (或是美國其它的州名), 然後點擊 "Run Tool" 按鈕

效果如下圖所示:

測試 get_forecast:

  • latitude: 36.7692
  • longitude: -119.4116

為什麼使用 SSE

這意味著 MCP 伺服器可以是某個運行在遠端的進程服務，AI Agent（客戶端）可以隨時隨地連接、使用和斷開連接。換句話說，基於 SSE 的伺服器和客戶端可以是解耦的進程（甚至可能在解耦的節點上）。

與客戶端本身將伺服器作為子進程生成的基於 STDIO 的模式相比，這是不同的，並且更適合「雲端原生」用例。

MCP Server

server.py 是 SSE-based MCP server, 預設情況下，伺服器運行在 0.0.0.0:5488 上運行，但可以使用命令列參數進行配置，例如：

uv run server.py --host <your host> --port <your port>
No tools information available.
No content found.