# Weather & Location MCP Server

A beginner-friendly MCP server built with TypeScript, Node.js, the MCP TypeScript SDK, OpenWeather API, dotenv, and zod.

## Features

- `getCurrentWeather(city)`
- `getForecast(city)`
- `getAirQuality(city)`
- Sunrise and sunset information
- Environment variable support with `dotenv`
- Input validation with `zod`
- TypeScript response types for API data
- Helpful error handling

## Tech Stack

- TypeScript
- Node.js
- `@modelcontextprotocol/sdk`
- OpenWeather API
- `dotenv`
- `zod`

## Project Structure

```text
weather-location-mcp-server/
|- src/
|  |- index.ts
|  |- weatherApi.ts
|  `- types.ts
|- .env.example
|- .gitignore
|- package.json
|- README.md
`- tsconfig.json
```

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Create your environment file

Create a `.env` file in the project root:

```env
OPENWEATHER_API_KEY=your_api_key_here
```

You can copy from `.env.example` and replace the placeholder value with your real OpenWeather API key.

### 3. Build the project

```bash
npm run build
```

## Run the Server

### Development mode

```bash
npm run dev
```

### Production build

```bash
npm run build
npm run start
```

The server runs over stdio, so it will wait quietly for an MCP client to connect.

## Available Tools

### `getCurrentWeather`

Input:

```json
{
  "city": "Delhi"
}
```

Returns:

- City name
- Country
- Weather condition and description
- Temperature
- Feels-like temperature
- Humidity
- Sunrise time
- Sunset time

### `getForecast`

Input:

```json
{
  "city": "Delhi"
}
```

Returns:

- City name
- Country
- First 5 forecast entries
- Temperature
- Weather condition and description

### `getAirQuality`

Input:

```json
{
  "city": "Delhi"
}
```

Returns:

- AQI value
- AQI label
- CO
- NO2
- O3
- PM2.5
- PM10

## Using with Codex

If you want Codex to use this server as an MCP tool provider, add a project config file at `.codex/config.toml`:

```toml
[mcp_servers.weather_location]
command = "node"
args = ["dist/index.js"]
cwd = "D:\\My PC\\Coding\\web development\\Weather & Location MCP Server"
enabled = true
startup_timeout_sec = 20
tool_timeout_sec = 60
```

Then restart Codex or open a new thread in the project.

## Notes

- Keep `.env` out of GitHub because it contains your API key.
- Keep `.codex/` out of GitHub if it contains your personal local Codex setup.
- This project uses Node.js native `fetch`.

## License

ISC