# Weather MCP Server

A Model Context Protocol (MCP) server that provides weather forecasts and geocoding lookup using the free, keyless Open-Meteo APIs. This server enables LLMs (like Claude, Gemini, and GPT) to query real-time weather information and multi-day forecasts for any city or location in the world.

## Features

- **Get Current Weather:** Detailed current conditions including condition description, temperature, apparent temperature (feels like), humidity, wind speed, and precipitation details.
- **Multi-day Weather Forecast:** Standard 1-7 day forecast with conditions, daily min/max temperatures, and total expected precipitation.
- **Keyless & Free:** Powered by the open-source [Open-Meteo](https://open-meteo.com/) APIs, requiring no API keys or subscription signups.
- **Fuzzy Geocoding:** Automatically resolves location names (e.g., "Paris", "New York", "London") to geographic coordinates and timezones.

---

## Installation & Usage

You can run this server directly from npm using `npx`, or install it globally.

### Method 1: Using `npx` (Recommended)

To run the server without installation:

```bash
npx -y weather-mcp-server
```

### Method 2: Global Installation

Install the package globally:

```bash
npm install -g weather-mcp-server
```

Then run it:

```bash
weather-mcp-server
```

---

## Configuration for MCP Clients

### 1. Claude Desktop

To add the Weather MCP Server to Claude Desktop, edit your `claude_desktop_config.json` file.

- **Windows path:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS path:** `~/Library/Application Support/Claude/claude_desktop_config.json`

Add the server to the `mcpServers` list:

```json
{
  "mcpServers": {
    "weather": {
      "command": "npx",
      "args": [
        "-y",
        "weather-mcp-server"
      ]
    }
  }
}
```

### 2. Cursor

Cursor supports custom MCP servers directly from the GUI:

1. Open **Cursor Settings** (`Ctrl + ,` or `Cmd + ,`).
2. Go to **Features** -> **MCP**.
3. Click **+ Add New MCP Server**.
4. Fill in:
   - **Name:** `Weather`
   - **Type:** `command`
   - **Command:** `npx -y weather-mcp-server`
5. Click **Save**.

---

## Tool Documentation

This server exposes a single tool called `get_weather`.

### `get_weather`

Gets the current weather and daily forecast for a given location.

**Arguments:**
- `location` (string, required): The city, region, or location name (e.g. `"Tokyo"`, `"Paris"`, `"Chicago, IL"`).
- `days` (number, optional, default: `3`): Number of forecast days to return (integer between `1` and `7`).

**Example Request:**
```json
{
  "name": "get_weather",
  "arguments": {
    "location": "Paris",
    "days": 3
  }
}
```

---

## Development & Building

If you want to run the server locally from the source code, follow these steps:

1. Clone or download the repository.
2. Install dependencies:
   ```bash
   npm install
   ```
3. Build the TypeScript code:
   ```bash
   npm run build
   ```
4. Run locally:
   ```bash
   npm start
   ```

To link and test the local version in Claude Desktop, point the configuration directly to the local path:

```json
{
  "mcpServers": {
    "weather-local": {
      "command": "node",
      "args": [
        "C:/path/to/your/project/dist/index.js"
      ]
    }
  }
}
```

## License

ISC License. Feel free to use and adapt this server.