mcp-weather

☁️ mcp-weather: Model Context Protocol (MCP) Weather Server Overview mcp-weather is a lightweight, Python-based server that demonstrates the integration of real-time weather data with AI models through the Model Context Protocol (MCP). This project enables AI assistants and large language models (LLMs) to access dynamic weather information, such as current conditions and forecasts, by exposing specialized "tools" that query external weather APIs.

The core purpose of mcp-weather is to showcase how to build an MCP server, connect it to a third-party service (OpenWeatherMap is used by default), and make that functionality discoverable and usable by any MCP-compatible AI client. This enhances the AI's ability to provide contextually relevant and up-to-date responses regarding meteorological data.

✨ Features Real-time Weather Queries: Obtain current weather conditions for any specified global city.

Multi-Day Forecasts: Retrieve detailed weather forecasts for upcoming days.

MCP Compatibility: Fully compatible with the Model Context Protocol, allowing seamless integration with various AI clients that support MCP.

Asynchronous Operations: Utilizes httpx for efficient, non-blocking HTTP requests to external weather APIs.

Secure API Key Management: Supports environment variables for securely managing sensitive API keys via a .env file.

🚀 Prerequisites Before setting up mcp-weather, ensure you have the following installed on your system:

Python 3.8 or higher: The MCP Python SDK requires a recent version of Python.

uv (recommended) or pip: A modern and fast Python package installer and manager. You can install uv via:

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

On Windows, please refer to the official uv installation guide for instructions.

OpenWeatherMap API Key: This project uses the OpenWeatherMap API for weather data. A free API key is typically sufficient for development and testing. Register for one at openweathermap.org.

🛠️ Installation Follow these steps to set up and run your mcp-weather server locally:

Clone the repository:

git clone https://github.com/githubmilind/mcp-weather.git cd mcp-weather

Create and activate a virtual environment: It's best practice to use a virtual environment to manage project dependencies.

uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate

Install project dependencies:

uv add "mcp[cli]" httpx python-dotenv

Configure your OpenWeatherMap API Key: Create a new file named .env in the root directory of your mcp-weather project (where weather_server.py is located). Add your OpenWeatherMap API key to this file:

OPENWEATHER_API_KEY=YOUR_OPENWEATHERMAP_API_KEY

Important: Replace YOUR_OPENWEATHERMAP_API_KEY with the actual API key you obtained from OpenWeatherMap.

⚡ Usage Running the MCP Weather Server To start the mcp-weather server:

Ensure your Python virtual environment is activated (as shown in the installation steps).

Navigate to your project's root directory in your terminal.

Execute the server script:

uv run weather_server.py

You will see a confirmation message indicating the server has started and is awaiting connections. Keep this terminal window open as long as you wish for the server to be available.

Connecting to an MCP-Compatible AI Client (Example: Claude for Desktop) To enable an AI client to use your mcp-weather server, you typically need to configure the client to recognize your local MCP server. The exact steps may vary depending on the specific AI client you are using. Here's a general example for Claude for Desktop:

Install Claude for Desktop: Ensure you have the latest version of Claude for Desktop installed.

Locate Client Configuration File:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

If this file does not exist, you may need to create it.

Add Server Configuration: Open the claude_desktop_config.json file in a text editor. Add or update the "mcpServers" section to include your mcp-weather server:

{ "mcpServers": { "weather": { "command": "/full/path/to/uv", "args": ["run", "weather_server.py"], "cwd": "/full/path/to/your/mcp-weather" } } }

Critical Replacements:

Replace /full/path/to/uv with the absolute path to your uv executable. You can find this path by running which uv (on macOS/Linux) or where uv (on Windows) in your active virtual environment.

Replace /full/path/to/your/mcp-weather with the absolute path to the directory where you cloned the mcp-weather project.

Save and Restart Client: Save the claude_desktop_config.json file and then close and restart your Claude for Desktop application for the changes to take effect.

Interact with the AI: Once configured, you can now prompt your AI client with weather-related questions. The AI should recognize the available tools from your mcp-weather server and use them to fetch data:

"What's the current temperature in Paris?"

"Give me the 3-day weather forecast for Sydney."

"How is the weather in Tokyo right now?"

Observe your mcp-weather server's terminal for activity as it processes requests from the AI client.

📸 Screenshots Here are visual examples of the mcp-weather server in action, illustrating its setup and interaction with an AI client:

Server Running in Terminal: A screenshot showing the command-line output when the mcp-weather server is launched and listening for connections.

AI Client Configuration Example: An example screenshot demonstrating how the mcp-weather server is configured within the settings of an MCP-compatible AI client, such as Claude for Desktop.

AI Responding with Current Weather: A visual of an AI client successfully querying mcp-weather for current weather conditions and presenting the retrieved information in a conversational format.

AI Providing Weather Forecast: An illustration of an AI client utilizing mcp-weather to generate and display a multi-day weather forecast based on a user's request.

🤝 Contributing Contributions, issues, and feature requests are welcome! Feel free to check the issues page.

To contribute:

Fork the repository.

Create a new branch (git checkout -b feature/your-feature-name).

Implement your changes.

Commit your changes (git commit -m 'Add new feature').

Push to the branch (git push origin feature/your-feature-name).

Open a Pull Request with a clear description of your changes.

📄 License This project is licensed under the MIT License. See the LICENSE file in this repository for full details.

🙏 Acknowledgements The developers of the Model Context Protocol (MCP) for enabling powerful AI integrations.

OpenWeatherMap for providing a comprehensive and accessible weather API.

The uv project for its efficient Python dependency management.