# Weather MCP Server
A Model Context Protocol (MCP) server that provides weather forecasts and alerts using the US National Weather Service API. **Requires GitHub authentication** to access weather tools.
## Features
- **GitHub Authentication**: Secure access using GitHub personal access tokens
- **Weather Forecasts**: Get detailed weather forecasts for any US location by coordinates
- **Weather Alerts**: Retrieve active weather alerts by state code
## Installation
### NPM Installation
```bash
npm install -g @dmitry-melnishin/mcp-weather
```
### Usage in VS Code
Add this to your MCP settings file (`.vscode/mcp.json` or global settings):
```json
{
"mcpServers": {
"weather": {
"command": "npx",
"args": ["-y", "@dmitry-melnishin/mcp-weather"]
}
}
}
```
Or if installed globally:
```json
{
"mcpServers": {
"weather": {
"command": "mcp-weather"
}
}
}
```
## Authentication Setup
Before using the weather tools, you must authenticate with GitHub:
1. **Create a GitHub Personal Access Token**:
- Go to GitHub Settings → Developer settings → Personal access tokens → Tokens (classic)
- Click "Generate new token (classic)"
- You don't need to select any scopes - just name it (e.g., "MCP Weather")
- Click "Generate token" and copy the token
2. **Authenticate in MCP**:
- Use the `authenticate` tool with your GitHub token
- Once authenticated, you can use all weather tools
**Example authentication:**
```
Tool: authenticate
Parameters: { "token": "ghp_your_github_token_here" }
```
## Available Tools
### authenticate
Authenticate with GitHub using a personal access token.
**Parameters:**
- `token` (string): GitHub personal access token
**Returns:** Success message with authenticated username or error message.
**Note:** You must authenticate before using any weather tools.
### get_forecast
Get weather forecast for a location. **Requires authentication.**
**Parameters:**
- `latitude` (number): Latitude of the location (-90 to 90)
- `longitude` (number): Longitude of the location (-180 to 180)
**Example:**
```
Get forecast for latitude 40.7128, longitude -74.0060
```
### get_alerts
Get weather alerts for a US state. **Requires authentication.**
**Parameters:**
- `state` (string): Two-letter state code (e.g., "CA", "NY")
**Example:**
```
Get weather alerts for CA
```
## Security Notes
- Your GitHub token is only stored in memory during the server session
- The token is never logged or persisted to disk
- No specific GitHub permissions/scopes are required
- The token is only used to verify your identity with GitHub
## Development
### Prerequisites
- Node.js 18 or higher
- npm or yarn
### Setup
```bash
git clone https://github.com/your-username/mcp-weather
cd mcp-weather
npm install
```
### Build
```bash
npm run build
```
### Local Testing
You can test the server locally by running:
```bash
node build/index.js
```
## API Source
This server uses the [National Weather Service API](https://www.weather.gov/documentation/services-web-api), which provides weather data for US locations only.
## License
MIT
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
