Shubham-Saboo/NCEI-MCP-Server

NCEI ADS MCP Server

A Model Context Protocol (MCP) server for NOAA NCEI Access Data Service API - access weather and climate data through Claude Desktop.

Features

• 🌦️ Full API Coverage: All official NCEI ADS parameters supported
• 🔍 Station Finder: Find nearest weather station by address, zipcode, or coordinates
• 📊 Multiple Formats: JSON, CSV, SSV
• 🗓️ Flexible Dates: ISO 8601 dates and timestamps with timezone support
• 🗺️ Geographic Filtering: Bounding box queries
• 📏 Unit Conversion: Standard or metric units
• ⚡ Production Ready: Comprehensive error handling and testing
• 🏗️ Modular Architecture: Clean separation of concerns for maintainability

Quick Start

1. Install uv

# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Configure Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ncei-ads": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/Shubham-Saboo/NCICS-MCP.git",
        "ncei-ads-mcp"
      ]
    }
  }
}

3. Restart Claude Desktop

That's it! The server will automatically download, set up, and run.

Available Tools

1. Find Nearest Station

Discover station IDs by address, zipcode, or coordinates. Returns the closest weather station with its ID.

Example Prompts:

• "Find the nearest daily-summaries station to New York, NY"
• "What's the closest weather station to zipcode 02101?"
• "Find a global-hourly station near latitude 42.3601, longitude -71.0589"

Parameters:

• dataset - Dataset name (e.g., "daily-summaries", "global-hourly")
• location - Address or zipcode (e.g., "Boston, MA" or "02101")
• OR latitude + longitude - Coordinates in decimal degrees
• radius_km - Search radius (default: 50km, max recommended: 200km)

Returns:

• Station ID (use with fetch_data tool)
• Station name and coordinates
• Distance from your location
• Ready-to-use example

2. Fetch Weather Data

Retrieve historical weather and climate data from NCEI.

Example Prompts:

• "Get temperature data for station USW00094728 from Jan 1-3, 2024"
• "Fetch marine wind data in the North Atlantic for January 2016"

Daily Temperature Data:

dataset: daily-summaries
startDate: 2024-01-01
endDate: 2024-01-03
stations: USW00094728
dataTypes: TMAX,TMIN,PRCP
units: metric
format: json

Marine Data with Bounding Box:

dataset: global-marine
startDate: 2016-01-01
endDate: 2016-01-02
boundingBox: 90,-180,-90,180
dataTypes: WIND_DIR,WIND_SPEED
format: csv

See for 14+ comprehensive test cases.

Supported Parameters

Required:

• dataset - Dataset identifier (e.g., "daily-summaries", "global-marine")
• startDate - ISO 8601 date (YYYY-MM-DD or YYYY-MM-DDTHH:mm:ssZ)
• endDate - ISO 8601 date

Optional:

• stations - Comma-separated station IDs
• dataTypes - Comma-separated data type codes
• boundingBox - Geographic filter as "N,W,S,E"
• units - "standard" or "metric"
• format - "json" (default), "csv", or "ssv"
• includeAttributes, includeStationName, includeStationLocation - Boolean flags
• options - Advanced options string

Documentation: https://www.ncei.noaa.gov/support/access-data-service-api-user-documentation

Development

Local Setup

git clone https://github.com/Shubham-Saboo/NCICS-MCP.git
cd NCICS-MCP
uv pip install -e ".[dev]"

Running Tests

uv run pytest tests/ -v

All tests pass, covering:

• Data fetching (all formats: JSON, CSV, SSV)
• HTTP error handling (400, 500)
• Timeout and connection errors
• Parameter validation
• Modular architecture (API client, utilities, tools)

Project Structure

src/ncei_ads_mcp/
├── server.py              # Main MCP server with tool registration
├── api/
│   ├── client.py          # HTTP client for NCEI API
│   └── endpoints.py       # API URLs
├── tools/
│   ├── fetch_data.py      # Data fetching tool
│   └── find_station.py    # Station finder tool
└── utils/
    ├── distance.py        # Haversine distance calculations
    ├── geocoding.py       # Address to coordinates conversion
    └── error_handlers.py  # HTTP error handling

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Run tests
4. Submit a Pull Request

License

MIT License - see

Acknowledgments

• Built with Model Context Protocol
• Data from NOAA NCEI