# Weather MCP Server

A complete Model Context Protocol (MCP) server that provides weather information through tools, resources, and prompts, designed for integration with Cursor IDE.

## What is MCP (Model Context Protocol)?

MCP is a protocol that enables AI assistants (like Cursor) to connect to external data sources and tools. It allows AI models to:

- **Call Tools**: Execute functions to perform actions (e.g., fetch weather data, query databases)
- **Read Resources**: Access structured data from external sources (e.g., files, APIs, databases)
- **Use Prompts**: Leverage reusable prompt templates for consistent interactions

### How MCP Works

```
┌─────────────┐         MCP Protocol         ┌──────────────┐
│   Cursor    │ ◄──────────────────────────► │  MCP Server  │
│     IDE     │     (stdin/stdout or HTTP)    │  (Python)    │
└─────────────┘                               └──────────────┘
      │                                              │
      │  Calls tools, reads resources,              │
      │  uses prompts                               │
      │                                              │
      └──────────────────────────────────────────────┘
                    External APIs/Data
```

The MCP server acts as a bridge between the AI assistant and external services, providing a standardized interface for accessing data and functionality.

## Features

This Weather MCP Server provides:

### Tools
- `get_current_weather(location: str)` - Fetch current weather conditions for a location
- `get_weather_forecast(location: str, days: int)` - Get multi-day weather forecast
- `search_locations(query: str)` - Search for location names

### Resources
- `weather://current/{location}` - Current weather data as a readable resource
- `weather://forecast/{location}` - Forecast data as a readable resource

### Prompts
- `analyze_weather` - Template for analyzing weather patterns and conditions
- `compare_locations` - Template for comparing weather between different locations

## Setup

### Prerequisites

- Python 3.12 or higher
- `uv` package manager (or pip)

### Installation

1. Install dependencies:
```bash
uv sync
# or
pip install -r requirements.txt
```

2. Set up environment variables (optional, for real API):
   
   Create a `.env` file in the project root:
   ```bash
   # .env
   WEATHER_API_KEY=your_api_key_here
   ```
   
   Get a free API key from [OpenWeatherMap](https://openweathermap.org/api)
   
   Note: If no API key is provided, the server will use mock data for demonstration purposes.

### Running the Server

```bash
python main.py
```

The server will start and communicate via stdio (standard input/output), which is the standard transport for MCP servers in Cursor IDE.

## Cursor IDE Integration

To use this MCP server in Cursor IDE:

1. Open Cursor IDE settings (Cmd/Ctrl + ,)
2. Navigate to **Features** → **MCP Servers** (or search for "MCP" in settings)
3. Click **Add Server** or edit the MCP servers configuration
4. Add the following configuration (update the path to match your project location):

```json
{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/Users/pratik/weather/main.py"
      ],
      "env": {}
    }
  }
}
```

   **Important**: Replace `/Users/pratik/weather/main.py` with the absolute path to your `main.py` file.

5. Save the configuration
6. Restart Cursor IDE
7. The AI assistant can now use the weather tools, resources, and prompts!

**Alternative**: You can also copy the configuration from `cursor_mcp_config.json` and merge it into your Cursor settings.

## Usage Examples

Once integrated with Cursor IDE, you can ask the AI assistant:

- "What's the weather in New York?"
- "Get a 5-day forecast for London"
- "Compare the weather in San Francisco and Seattle"
- "Search for locations matching 'Paris'"

The AI will automatically use the appropriate MCP tools, resources, or prompts to fulfill your request.

![Weather MCP Server Usage Example](screenshot.png)

*Example: Asking "What's the weather in New York?" in Cursor IDE with the Weather MCP Server*

## Architecture

```
┌─────────────┐
│   Cursor    │
│     IDE     │
└──────┬──────┘
       │ MCP Protocol
       │
┌──────▼──────────────────┐
│   MCP Weather Server    │
│  (main.py)              │
├─────────────────────────┤
│ • Tools                 │
│ • Resources             │
│ • Prompts               │
└──────┬──────────────────┘
       │
┌──────▼──────────┐
│ Weather API     │
│ (weather_api.py)│
└─────────────────┘
```

## Development

### Project Structure

```
weather/
├── main.py                 # MCP server implementation
├── weather_api.py          # Weather API client
├── pyproject.toml          # Dependencies
├── cursor_mcp_config.json  # Cursor IDE configuration
├── .env.example            # Environment template
└── README.md               # This file
```

### Adding New Features

- **New Tools**: Add functions to the `tools` list in `main.py`
- **New Resources**: Add URI patterns to the `resources` list in `main.py`
- **New Prompts**: Add prompt templates to the `prompts` list in `main.py`

## License

MIT