Weather MCP Server

A Model Context Protocol (MCP) server built with fastmcp that exposes exactly 5 weather tools from one API provider (Open-Meteo) — each tool calls a different endpoint on that provider.

Includes a Groq-powered LLM agent and a browser inbox UI. You ask a weather question in plain English; the LLM picks the right Open-Meteo endpoint tool, calls it, and returns an HTML answer. The UI shows which MCP tool was actually called for each query.

---

Architecture Diagram

flowchart LR
    classDef browser fill:#e0f2fe,stroke:#0284c7,color:#0f172a,stroke-width:1.5px;
    classDef agent fill:#ede9fe,stroke:#7c3aed,color:#0f172a,stroke-width:1.5px;
    classDef mcp fill:#dcfce7,stroke:#16a34a,color:#0f172a,stroke-width:1.5px;
    classDef api fill:#fef3c7,stroke:#d97706,color:#0f172a,stroke-width:1.5px;
    classDef store fill:#f8fafc,stroke:#64748b,color:#0f172a,stroke-width:1px;

    subgraph Browser["Browser UI - index.html :8080"]
        Q["User asks weather question"]:::browser
        H["GET /health"]:::browser
        C["POST /chat { question }"]:::browser
        R["Render tool_used + HTML answer"]:::browser
    end

    subgraph Agent["Groq Agent - agent.py :8001"]
        A1["FastAPI routes"]:::agent
        A2["MCP SSE client"]:::agent
        A3["Groq call #1<br/>pick best tool + extract city"]:::agent
        A4["Groq call #2<br/>format final HTML answer"]:::agent
    end

    subgraph MCP["Weather MCP Server - server.py :8000"]
        M0["SSE endpoint /sse"]:::mcp
        M1["open_meteo_geocode"]:::mcp
        M2["open_meteo_current"]:::mcp
        M3["open_meteo_forecast"]:::mcp
        M4["open_meteo_air_quality"]:::mcp
        M5["open_meteo_historical"]:::mcp
    end

    subgraph OpenMeteo["Open-Meteo provider"]
        E1["/v1/search"]:::api
        E2["/v1/forecast<br/>current weather"]:::api
        E3["/v1/forecast<br/>5-day forecast"]:::api
        E4["/v1/air-quality"]:::api
        E5["/v1/archive"]:::api
    end

    K[".env<br/>GROQ_API_KEY<br/>MCP_SSE_URL"]:::store

    Q --> C
    H --> A1
    C --> A1
    A1 --> A2
    A1 --> A3
    A3 -->|"tool choice + city"| A2
    A2 -->|"list_tools() + call_tool()"| M0
    M0 --> M1
    M0 --> M2
    M0 --> M3
    M0 --> M4
    M0 --> M5
    M1 --> E1
    M2 --> E2
    M3 --> E3
    M4 --> E4
    M5 --> E5
    M0 -->|"HTML tool result"| A4
    A4 -->|"tool_used + html"| R
    K --> A1

---

Query Flow

sequenceDiagram
    autonumber
    participant U as Browser UI
    participant AG as agent.py
    participant G as Groq
    participant M as server.py
    participant O as Open-Meteo

    U->>AG: GET /health
    AG->>M: list_tools() over SSE
    M-->>AG: 5 available open_meteo_* tools
    AG-->>U: agent ok, MCP status, Groq configured

    U->>AG: POST /chat {question}
    AG->>M: list_tools() over SSE
    M-->>AG: tool schemas
    AG->>G: Question + tool schemas
    G-->>AG: Selected tool + city args
    AG->>M: call_tool(tool_name, {city})
    M->>O: HTTP GET to chosen endpoint
    O-->>M: live JSON weather data
    M-->>AG: HTML tool result
    AG->>G: User question + tool name + tool HTML
    G-->>AG: final HTML answer
    AG-->>U: { tool_used, html }
    U->>U: Show tool bar and answer card

---

The 5 Tools — One Provider, Five Endpoints

#	MCP Tool	Open-Meteo Endpoint	What it returns
1	open_meteo_geocode	geocoding-api.open-meteo.com/v1/search	Coordinates, timezone, region
2	open_meteo_current	api.open-meteo.com/v1/forecast	Current temp, humidity, wind, conditions
3	open_meteo_forecast	api.open-meteo.com/v1/forecast	5-day daily high/low, rain
4	open_meteo_air_quality	air-quality-api.open-meteo.com/v1/air-quality	AQI, PM2.5, PM10, ozone
5	open_meteo_historical	archive-api.open-meteo.com/v1/archive	Yesterday's min/max temp, conditions

All 5 tools use Open-Meteo only — free, no weather API key required.

API Keys

Key	Required for	Sign up
GROQ_API_KEY	LLM inbox UI (agent.py)	https://console.groq.com/keys (free tier)

Weather tools need no API key. Only Groq is required for the inbox UI.

copy .env.example .env
# Edit .env — add GROQ_API_KEY

---

Quick Start

1. Install dependencies

git clone https://github.com/RimeetMavani/weather-mcp--build.git
cd weather-mcp--build
pip install -r requirements.txt

2. Configure Groq API key

copy .env.example .env
# Edit .env — add GROQ_API_KEY (required for LLM inbox)

3. Start the MCP server (SSE on port 8000)

python server.py

You should see:

Starting MCP server 'Weather MCP Server' with transport 'sse' on http://127.0.0.1:8000/sse

Keep this terminal open.

4. Start the LLM agent (port 8001)

Open a second terminal:

python agent.py

5. Serve the HTML inbox UI (port 8080)

Open a third terminal:

python -m http.server 8080

6. Open the browser UI

Go to: http://localhost:8080/index.html

1. Wait for status dots to turn green (agent, MCP, LLM)
2. Type a weather question or click a suggested question
3. After each query, the MCP tool called bar shows the exact tool the LLM picked (e.g. open_meteo_forecast) and its endpoint
4. View the HTML-formatted answer below

---

Inbox UI — Dynamic Tool Display

The UI does not show a fixed tool name before you ask. After each query:

UI element	What it shows
Tool called bar	Exact MCP tool name + Open-Meteo endpoint used for this query
HTML answer card	Groq-formatted weather answer (badge shows the specific tool name)
Suggested questions	Plain questions only — no pre-assigned tool labels

Example after asking "Give me the 5-day forecast for Tokyo":

MCP tool called:  open_meteo_forecast  →  api.open-meteo.com/v1/forecast

---

5 Suggested Inbox Questions

Question	Tool the LLM typically picks
What's the weather in London right now?	open_meteo_current
Give me the 5-day forecast for Tokyo	open_meteo_forecast
What's the air quality in Paris?	open_meteo_air_quality
What were the coordinates and timezone for New York?	open_meteo_geocode
How was the weather in Sydney yesterday?	open_meteo_historical

The actual tool chosen is shown in the UI after each query — the LLM may pick a different tool if it fits the question better.

---

CLI Test (all 5 tools)

With server.py running in another terminal:

python test_client.py

Connects via SSE, lists all 5 tools, calls each with a live city, and prints a pass/fail summary. No Groq agent needed for this test.

---

Project Files

File	Purpose
server.py	MCP server — 5 Open-Meteo endpoint tools, SSE transport
agent.py	Groq LLM agent — picks MCP tool, returns tool_used + HTML
index.html	Inbox UI — status panel, dynamic tool bar, HTML answers
test_client.py	Terminal script to test all 5 MCP tools directly
requirements.txt	Python dependencies
.env.example	Template for Groq API key

---

Ports Summary

Port	Service	Command
8000	MCP server (SSE)	python server.py
8001	Groq LLM agent	python agent.py
8080	Browser UI	python -m http.server 8080

---

End Testing

1. Close the browser tab
2. Stop the HTML server: Ctrl+C
3. Stop the agent: Ctrl+C
4. Stop the MCP server: Ctrl+C