MCP Weather Demo

A demo-ready Model Context Protocol (MCP) project that connects a Google Gemini agent to a weather MCP server. The agent discovers weather tools automatically and answers natural-language questions using live data from the free wttr.in API — no weather API key required.

What This Demo Shows

• MCP Server (server.py) — exposes 4 weather tools (current weather, daily/hourly forecasts, city comparison).
• MCP Client (client.py) — a Gemini-powered agent that calls those tools and summarizes results in plain English.
• Flexible transport — switch between HTTP (default) and stdio via .env.
• Clean configuration — secrets in .env, dependencies in requirements.txt.

Architecture / Pseudo-flow

flowchart LR
    User -->|prompt| Client
    Client -->|generate_content tools=[session]| Gemini
    Gemini -->|tool call| Client
    Client -->|MCP call_tool| Server
    Server -->|HTTP| WTTR
    WTTR --> Server --> Client --> Gemini
    Gemini -->|final answer| User

Loading

Request lifecycle:

1. You type a question in the client REPL.
2. The client sends your prompt to Google Gemini along with the live MCP session as a tool.
3. Gemini decides which weather tool(s) to call.
4. The client forwards tool calls to the MCP server over HTTP or stdio.
5. The server fetches data from wttr.in and returns structured JSON.
6. Gemini synthesizes a natural-language answer and prints it back to you.

Project Structure

MCP/
├── client.py          # Gemini agent + MCP client (interactive REPL)
├── server.py          # MCP server with weather tools
├── weather_api.py     # wttr.in API wrapper (no API key needed)
├── requirements.txt   # Python dependencies
├── .env.example       # Environment variable template
├── .gitignore
└── README.md

Prerequisites

• Python 3.10+
• A Google Gemini API key (free tier available at Google AI Studio)

Setup

1. Create a virtual environment

cd MCP
python -m venv .venv
.venv\Scripts\activate

2. Install dependencies

pip install -r requirements.txt

3. Configure environment variables

copy .env.example .env

Edit .env and set your Gemini API key:

GEMINI_API_KEY=your_actual_api_key_here
GEMINI_MODEL=gemini-2.5-flash

MCP_TRANSPORT=http
MCP_HTTP_HOST=127.0.0.1
MCP_HTTP_PORT=8000
MCP_HTTP_PATH=/mcp

Variable	Description	Default
GEMINI_API_KEY	Google Gemini API key (required)	—
GEMINI_MODEL	Gemini model name	gemini-2.5-flash
MCP_TRANSPORT	http or stdio	http
MCP_HTTP_HOST	HTTP server bind address	127.0.0.1
MCP_HTTP_PORT	HTTP server port	8000
MCP_HTTP_PATH	MCP HTTP endpoint path	/mcp

Running the Demo

Option A — HTTP mode (default, two terminals)

Terminal 1 — start the MCP server:

python server.py

You should see:

[Weather MCP Server] Starting with HTTP transport at http://127.0.0.1:8000/mcp

Terminal 2 — start the Gemini client:

python client.py

Option B — stdio mode (single terminal)

Set in .env:

MCP_TRANSPORT=stdio

Then run only the client (it launches the server as a subprocess):

python client.py

Example Prompts

Try these once the client is running:

• What's the weather in Tokyo, Japan right now?
• Compare the weather between Mumbai, India and London, UK.
• Will it rain in Paris in the next 12 hours?
• Give me a 3-day forecast for New York, US.

Type quit or exit to leave the REPL.

Available MCP Tools

Tool	Description
get_current_weather	Current temperature, humidity, wind, conditions
get_daily_forecast	Daily min/max temps (up to 3 days)
get_hourly_forecast	3-hourly forecast slots (up to 24 slots / 3 days)
compare_weather	Side-by-side current weather for two cities

wttr.in Limitations

• No API key required — free for non-commercial use.
• Daily forecast: up to 3 days.
• Hourly forecast: 3-hourly intervals (8 slots per day).
• Requires a curl-style User-Agent (handled automatically in weather_api.py).
• For best location accuracy, use "City, Country" format (e.g. Tokyo, Japan) or City@cc (e.g. London@uk).

Troubleshooting

Issue	Fix
Set GEMINI_API_KEY in your .env file	Copy .env.example → .env and add your key
Client can't connect (HTTP mode)	Make sure server.py is running in another terminal
City not found	Try a more specific name, e.g. "Paris, France"
wttr.in timeout	Check internet connection; wttr.in may be temporarily slow
Port already in use	Change MCP_HTTP_PORT in .env (e.g. 8001)
Gemini model error	Try GEMINI_MODEL=gemini-2.5-flash-lite in .env

License

Demo code — free to use and share.