Open-Meteo AI Assistant using Model Context Protocol (MCP)

Overview

The Open-Meteo AI Assistant is a production-style Python project demonstrating how to build an AI application using the Model Context Protocol (MCP).

Unlike a traditional CRUD application, this project exposes weather capabilities through an MCP Server while an AI-powered MCP Client discovers available tools, lets an LLM decide which tool to invoke, executes the selected tool, and transforms structured responses into natural language.

The project also demonstrates Server-Initiated LLM Sampling, where the MCP server requests the connected AI client to generate content while executing a tool.

---

Architecture

                              User
                                │
                                ▼
                      OpenAI Responses API
                                │
                                ▼
                  assistant/ai_client.py
                     (AI Assistant / MCP Client)
                                │
                                ▼
                     MCP Protocol (stdio)
                                │
                                ▼
                  Open-Meteo MCP Server
                          (main.py)
                                │
            ┌───────────────────┼────────────────────┐
            │                   │                    │
            ▼                   ▼                    ▼
      get_weather       compare_weather     generate_packing_advice
                                                    │
                                                    ▼
                                          weather_client.py
                                                    │
                                                    ▼
                                            Open-Meteo REST API
                                                    │
                                                    ▼
                                      Live weather / forecast data
                                                    │
                                                    ▼
                                   Server-Initiated LLM Sampling
                                                    │
                                                    ▼
                                     assistant/ai_client.py
                                      (sampling callback)
                                                    │
                                                    ▼
                                               OpenAI Model

---

Project Structure

open-meteo-mcp/
│
├── assistant/
│   ├── client.py
│   ├── ai_client.py
│   └── test_llm.py
│
├── tests/
│
├── main.py
├── weather_client.py
├── weather_models.py
├── errors.py
│
├── .env.example
├── .gitignore
├── pyproject.toml
├── uv.lock
└── README.md

---

Features

The MCP server currently exposes the following tools:

Tool	Description
search_city	Search for a city
get_weather	Retrieve current weather
get_weather_forecast	Retrieve multi-day weather forecast
compare_weather	Compare weather between two cities
find_warmest_day	Find the warmest forecast day
get_packing_context	Return forecast data for packing recommendations
generate_packing_advice	Demonstrates Server-Initiated LLM Sampling

---

Technologies

• Python 3.14
• Model Context Protocol (MCP)
• OpenAI Responses API
• Open-Meteo REST API
• httpx
• Pydantic
• pytest
• uv

---

Installation

Clone the repository:

git clone <repository-url>
cd open-meteo-mcp

Install dependencies:

uv sync

Activate the virtual environment:

source .venv/bin/activate

Create a .env file:

OPENAI_API_KEY=your-api-key
OPENAI_MODEL=gpt-4.1-mini

---

Running the Project

Start the MCP Inspector

uv run mcp dev main.py

The Inspector allows you to:

• Discover available MCP tools
• Execute tools manually
• Inspect schemas
• Debug tool responses

---

Run the AI Assistant

uv run python assistant/ai_client.py

Example:

You:
Compare the weather in Tunis and Munich

Assistant:
Tunis is currently warmer than Munich by 7.5°C.

Example:

You:
What should I pack for three days in Rome?

Assistant:
For your three-day trip to Rome...

---

Application Workflow

Standard MCP Tool Calling

User
    │
    ▼
OpenAI selects an MCP tool
    │
    ▼
MCP Client
    │
    ▼
MCP Server
    │
    ▼
Open-Meteo API
    │
    ▼
Structured response
    │
    ▼
OpenAI generates the final answer

---

Server-Initiated LLM Sampling

This project includes an educational implementation of Server-Initiated LLM Sampling.

Instead of the AI client generating all responses itself, the MCP server can request the connected client to invoke an LLM while executing a tool.

Workflow:

User
    │
    ▼
OpenAI selects generate_packing_advice
    │
    ▼
MCP Client
    │
    ▼
MCP Server
    │
    ▼
Open-Meteo API
    │
    ▼
Forecast retrieved
    │
    ▼
ctx.session.create_message(...)
    │
    ▼
Sampling Callback
    │
    ▼
OpenAI generates packing advice
    │
    ▼
Result returned to the MCP Server
    │
    ▼
Final response returned to the user

Note: Server-Initiated LLM Sampling is deprecated in the MCP 2026-07-28 specification. It is included here for educational purposes to demonstrate advanced MCP capabilities.

---

Example Queries

What's the weather in Paris?

Compare the weather between Tunis and Munich.

Find the warmest day in Rome this week.

What should I pack for five days in Rome?

---

Running Tests

Run the complete test suite:

uv run pytest -v

Compile all Python files:

uv run python -m py_compile \
main.py \
weather_client.py \
weather_models.py \
errors.py \
assistant/client.py \
assistant/ai_client.py

---

Learning Outcomes

This project demonstrates:

• Building an MCP Server
• Building an MCP Client
• MCP Tool Discovery
• MCP Tool Execution
• OpenAI Tool Calling
• OpenAI Responses API
• Server-Initiated LLM Sampling
• Async Python
• REST API Integration
• Pydantic Validation
• Error Handling
• Modular Software Architecture
• Separation of Concerns

---

Future Improvements

Possible enhancements include:

• Air Quality API
• Weather Alerts
• Historical Weather
• Docker Support
• GitHub Actions CI/CD
• Structured Logging
• Response Caching
• GitHub MCP Server
• Gitea MCP Server
• PostgreSQL MCP Server
• Filesystem MCP Server

---

License

This project is intended for educational and portfolio purposes.