# 🌤️ Weather MCP Server

A simple **Model Context Protocol (MCP) server** that provides weather alerts to AI assistants such as **Claude Code**.

The server runs locally and communicates with the MCP client using **stdio (standard input/output)**. It fetches weather information from an external weather API and exposes it as an MCP tool.

## Architecture

```text
Claude Code
     ↕
   stdio
     ↕
Weather MCP Server
     ↓
Weather API
```

The MCP server runs as a local Node.js process. It does **not** expose a web server or listen on a port such as `localhost:3000`.

## Features

* 🌡️ Get current weather alerts
* 📍 Query weather for a specified location
* 🔌 MCP-compatible tool interface
* 💻 Runs locally using stdio
* 📦 Installable through npm
* 🤖 Designed for use with Claude Code

## Requirements

* Node.js
* npm
* Claude Code
* An API key for the weather service, if required by the implementation

## Installation

### Using npm

The package is available on npm as:

```bash
npx rudra-weather-mcp
```

No global installation is required.

### From source

Clone the repository:

```bash
git clone <YOUR_GITHUB_REPOSITORY_URL>
cd weather
```

Install dependencies:

```bash
npm install
```

Run the server:

```bash
npm start
```

## Using with Claude Code

Add the MCP server to Claude Code:

```bash
claude mcp add weather -- npx rudra-weather-mcp
```

Claude Code will automatically start the MCP server locally when it needs to communicate with it.

You can verify the MCP configuration with:

```bash
claude mcp list
```

## Example Prompt

After adding the MCP server, ask Claude Code:

```text
Use the weather MCP server to get the current weather alerts in Boston, Massachusetts.

Do not answer from your own knowledge. Use the MCP tool.
```

Claude Code should invoke the weather MCP tool and return the information provided by the server.

## How It Works

MCP defines how an AI application communicates with external tools.

In this project, **stdio is the transport mechanism** used to send MCP messages between Claude Code and the local MCP server.

```text
Claude Code
    │
    │ MCP messages
    │
    ▼
  stdio
    │
    ▼
Weather MCP Server
    │
    │ HTTP request
    ▼
Weather API
    │
    │ Weather data
    ▼
Weather MCP Server
    │
    │ MCP response
    ▼
Claude Code
```

The MCP server itself is not an HTTP server. It runs as a local process and communicates through:

* `stdin` — receives messages from Claude Code
* `stdout` — sends responses to Claude Code
* `stderr` — used for errors/logging

## Local vs Remote MCP

This project is designed as a **local MCP server**.

### Local

```text
Claude Code
     ↕
   stdio
     ↕
MCP Server
```

Each user runs their own copy of the MCP server on their computer.

### Remote

A remote MCP server could instead communicate over HTTP:

```text
Claude Code
     ↓ HTTP
Remote MCP Server
     ↓
Weather API
```

This project does not currently require a remote server.

## Development

Start the server directly with:

```bash
npm start
```

The project uses:

* **TypeScript** — MCP server implementation
* **Node.js** — runtime
* **tsx** — TypeScript execution
* **Zod** — schema validation
* **MCP SDK** — MCP server implementation

## Project Structure

```text
weather/
├── bin/
│   └── weather-mcp.js
├── src/
│   └── index.ts
├── package.json
└── README.md
```

## npm Package

The published npm package is:

```text
rudra-weather-mcp
```

Run it with:

```bash
npx rudra-weather-mcp
```

## License

MIT