Weather Api

A Model Context Protocol (MCP) server that provides weather data tools for AI assistants and applications. This server integrates with the National Weather Service (NWS) API to deliver real-time weather forecasts and alerts for locations within the United States.

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: Direct integration with the official National Weather Service API
• MCP Protocol: Built using the Model Context Protocol SDK for seamless AI assistant integration

Installation

Prerequisites

• Node.js 18+
• npm or yarn

Setup

1. Clone the repository:

git clone <repository-url>
cd weather-mcp

2. Install dependencies:

npm install

3. Build the project:

npm run build:server

Usage

Running the MCP Server

Start the server:

npm run start:server

The server runs on stdio and is designed to be used with MCP-compatible AI assistants like Claude Desktop.

Available Tools

The server provides two main tools:

1. get-forecast

Retrieve 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)

Example Usage:

// Get forecast for San Francisco
{
  "tool": "get-forecast",
  "parameters": {
    "latitude": 37.7749,
    "longitude": -122.4194
  }
}

2. get-alerts

Retrieve active weather alerts for a US state.

Parameters:

• state (string): Two-letter state code (e.g., "CA", "NY", "TX")

Example Usage:

// Get alerts for California
{
  "tool": "get-alerts", 
  "parameters": {
    "state": "CA"
  }
}

Integration with AI Assistants

Claude Desktop Integration

To integrate with Claude Desktop, add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "weather": {
      "command": "node",
      "args": ["/path/to/weather-mcp/dist/core/server/index.js"]
    }
  }
}

Other MCP-Compatible Applications

This server follows the Model Context Protocol specification and can be integrated with any MCP-compatible application. The server communicates via stdio using the MCP protocol.

API Data Sources

This server uses the following National Weather Service endpoints:

• Forecasts: https://api.weather.gov/points/{lat},{lon} and associated forecast URLs
• Alerts: https://api.weather.gov/alerts?area={STATE}

Coverage

• Forecasts: All US territories and locations
• Alerts: All US states and territories (using two-letter state codes)

Development

Project Structure

src/
├── core/
│   ├── constants/     # API endpoints and configuration
│   ├── interfaces/    # TypeScript type definitions
│   ├── utils/         # Utility functions for API calls and formatting
│   ├── server/        # Server bootstrap and transport setup
│   └── index.ts       # Main MCP server implementation
└── client/            # (Empty - for future client implementations)

Building

The project uses TypeScript and compiles to the dist/ directory:

npm run build:server

Adding New Tools

To add new weather-related tools:

1. Define the tool schema in src/core/index.ts
2. Implement the tool handler function
3. Add any necessary interfaces in src/core/interfaces/index.ts
4. Add utility functions in src/core/utils/index.ts if needed

Example:

server.tool(
  "tool-name",
  "Tool description",
  {
    param1: z.string().describe("Parameter description"),
  },
  async ({ param1 }) => {
    // Implementation
    return {
      content: [
        {
          type: "text",
          text: "Result",
        },
      ],
    };
  }
);

Error Handling

The server includes comprehensive error handling:

• API Failures: Graceful handling of NWS API errors with informative messages
• Invalid Coordinates: Validation for latitude/longitude bounds
• Missing Data: Proper handling when forecast or alert data is unavailable
• Network Issues: Timeout and connection error handling

Dependencies

• @modelcontextprotocol/sdk: MCP server implementation
• @anthropic-ai/sdk: Anthropic SDK (for potential future features)
• zod: Runtime type validation
• dotenv: Environment variable management

License

ISC License

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

Support

For issues and questions:

• Check the National Weather Service API documentation for data availability
• Ensure your coordinates are within US territories for forecasts
• Verify state codes are valid two-letter abbreviations for alerts

Limitations

• US Only: The NWS API only provides data for US territories
• Rate Limits: Subject to National Weather Service API rate limits
• Data Availability: Some remote locations may not have detailed forecast data