README.MD•4.96 kB
# Weather MCP Server
A Model Context Protocol (MCP) server that provides weather information and alerts using the National Weather Service (NWS) API. This server enables AI assistants to access real-time weather data for US locations.
## Features
- **Weather Forecasts**: Get detailed weather forecasts for any US location using latitude/longitude coordinates
- **Weather Alerts**: Retrieve active weather alerts for any US state
- **NWS Integration**: Uses the official National Weather Service API for reliable, up-to-date weather data
- **MCP Compatible**: Works with any MCP-compatible AI assistant or application
## Available Tools
### `get_forecast`
Get weather forecast for a specific location.
**Parameters:**
- `latitude` (number): Latitude of the location (-90 to 90)
- `longitude` (number): Longitude of the location (-180 to 180)
**Returns:** Detailed weather forecast including temperature, wind conditions, and weather descriptions for multiple periods.
### `get_alerts`
Get active weather alerts for a US state.
**Parameters:**
- `state` (string): Two-letter state code (e.g., "CA", "NY", "TX")
**Returns:** List of active weather alerts including severity, affected areas, and descriptions.
## Prerequisites
- Node.js (version 14 or higher)
- npm or yarn
- An MCP-compatible client (like VS Code with GitHub Copilot)
## Installation
1. Clone the repository:
```bash
git clone <repository-url>
cd weather-mcp-server
```
2. Install dependencies:
```bash
npm install
```
## Building the Server
Build the TypeScript code to JavaScript:
```bash
npm run build
```
This will:
- Compile TypeScript files from `src/` to `build/`
- Make the main executable file executable (`chmod 755 build/index.js`)
## Usage with VS Code GitHub Copilot
To use this weather MCP server with VS Code GitHub Copilot, you need to update your MCP configuration:
### Step 1: Update MCP Configuration
Edit your `mcp.json` file (usually located in your VS Code settings directory) and add the weather server:
```json
{
"mcpServers": {
"weather": {
"command": "node",
"args": ["/Users/gshanka/Documents/ReactDev/weather-mcp-server/build/index.js"]
}
}
}
```
**Note:** Replace the path in `args` with the absolute path to your built `index.js` file.
### Step 2: Restart VS Code
After updating the configuration, restart VS Code to load the new MCP server.
### Step 3: Use Weather Tools
Once configured, you can ask GitHub Copilot for weather information:
- "What's the weather forecast for San Francisco?" (Copilot will ask for coordinates or you can provide: latitude 37.7749, longitude -122.4194)
- "Are there any weather alerts in California?" (Use state code "CA")
- "Get me the forecast for latitude 40.7128, longitude -74.0060" (New York City)
## Example Usage
### Getting Weather Forecast
```text
User: "What's the weather forecast for Seattle?"
Assistant: I'll get the weather forecast for Seattle (latitude: 47.6062, longitude: -122.3321).
[The server will return a detailed forecast with temperature, wind, and conditions for multiple periods]
```
### Getting Weather Alerts
```text
User: "Are there any weather alerts in Florida?"
Assistant: I'll check for weather alerts in Florida.
[The server will return any active weather alerts for the state of FL]
```
## Development
### Project Structure
```text
weather-mcp-server/
├── src/
│ ├── index.ts # Main MCP server implementation
│ └── weather-utils.ts # Weather API utilities and types
├── build/ # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md
```
### Running in Development
```bash
# Build and run
npm run build
node build/index.js
```
### Debugging
The server logs errors to stderr, which you can monitor when running the server directly or check in your MCP client's logs.
## API Limitations
- **US Only**: The National Weather Service API only provides data for US locations
- **Rate Limiting**: The NWS API has rate limits; avoid making excessive requests
- **Data Availability**: Some remote or maritime locations may not have forecast data available
## Contributing
1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Build and test the server
5. Submit a pull request
## License
ISC License - see package.json for details.
## Troubleshooting
### Server Not Loading
- Ensure the path in `mcp.json` points to the correct `build/index.js` file
- Verify the server was built successfully with `npm run build`
- Check VS Code's MCP logs for error messages
### No Weather Data
- Verify you're using valid US coordinates
- Check that the NWS API is accessible from your network
- Ensure you're using valid two-letter state codes for alerts
### Permission Errors
- Make sure the `build/index.js` file is executable
- The build script should handle this automatically with `chmod 755`