HCDP MCP Server

A Model Context Protocol (MCP) server that provides seamless access to the Hawaii Climate Data Portal (HCDP) API for AI assistants like Claude Code and Cursor.

Overview

The HCDP MCP Server enables AI assistants to query climate and weather data for Hawaii and American Samoa directly through the Model Context Protocol. This allows for natural language climate data analysis, visualization, and research workflows.

Features

• 🌧️ Climate Raster Data - Access rainfall, temperature, humidity maps and time series
• 📊 Station Data - Query meteorological station information and measurements
• 🌡️ Mesonet Data - Real-time weather station measurements
• 📦 Data Packages - Generate downloadable climate data archives
• 🗺️ Time Series Analysis - Extract data for specific coordinates and time ranges

Quick Start

1. Installation

# Clone the repository
git clone https://github.com/yourusername/hcdp-mcp.git
cd hcdp-mcp

# Install the package
pip install -e .

# Or install from PyPI (when available)
pip install hcdp-mcp-server

2. Get HCDP API Token

1. Visit the Hawaii Climate Data Portal
2. Create an account or log in
3. Navigate to your profile/API settings to generate a token

3. Configure Environment

# Copy example environment file
cp .env.example .env

# Edit .env with your API token
HCDP_API_TOKEN=your_token_here
HCDP_BASE_URL=https://api.hcdp.ikewai.org

⚠️ Security Note: Never commit your .env file to version control. It contains sensitive API credentials.

4. Test Installation

# Test the MCP server
hcdp-mcp-server

Desktop Application Integration

Claude Code Configuration

Method 1: Using MCP Add Command (Recommended)

The easiest way to set up the HCDP MCP server with Claude Code:

# Add the MCP server to Claude Code
claude mcp add hcdp

# This will automatically configure the server in your Claude settings

Method 2: Manual Configuration

Add to your Claude Code MCP settings (~/.config/claude-code/mcp_servers.json):

{
  "mcpServers": {
    "hcdp": {
      "command": "hcdp-mcp-server",
      "env": {
        "HCDP_API_TOKEN": "your_token_here"
      },
      "description": "Hawaii Climate Data Portal - Access climate and weather data for Hawaii and American Samoa"
    }
  }
}

Method 3: Using Environment File

If you prefer to use the .env file approach:

{
  "mcpServers": {
    "hcdp": {
      "command": "hcdp-mcp-server",
      "cwd": "/path/to/hcdp-mcp",
      "description": "Hawaii Climate Data Portal - Access climate and weather data for Hawaii and American Samoa"
    }
  }
}

Cursor Configuration

Add to your Cursor MCP settings (.cursor/mcp_servers.json in your project or global settings):

{
  "mcpServers": {
    "hcdp-climate-data": {
      "command": "hcdp-mcp-server",
      "env": {
        "HCDP_API_TOKEN": "your_token_here"
      },
      "args": []
    }
  }
}

Visual Studio Code with MCP Extension

If using VS Code with an MCP extension, add to settings.json:

{
  "mcp.servers": {
    "hcdp": {
      "command": "hcdp-mcp-server",
      "env": {
        "HCDP_API_TOKEN": "your_token_here"
      }
    }
  }
}

Available Tools

get_climate_raster

Retrieve climate data maps (GeoTIFF files) for rainfall, temperature, etc.

Required Parameters:

• datatype: Climate variable (e.g., 'rainfall', 'temp_mean', 'temp_min', 'temp_max')
• date: Date in YYYY-MM-DD format
• extent: Spatial extent (e.g., 'statewide', 'oahu', 'big_island')

Optional Parameters:

• location: 'hawaii' or 'american_samoa' (default: 'hawaii')
• production: Production level for rainfall data
• aggregation: Temporal aggregation for temperature data
• timescale: Timescale for SPI data
• period: Period specification

get_timeseries_data

Get time series climate data for specific coordinates.

Required Parameters:

• datatype: Climate variable
• start: Start date (YYYY-MM-DD)
• end: End date (YYYY-MM-DD)
• extent: Spatial extent

Optional Parameters:

• lat, lng: Latitude/longitude coordinates
• location: Geographic location
• production, aggregation, timescale, period: Data specifications

get_station_data

Query meteorological station information.

Required Parameters:

• q: MongoDB-style query (e.g., '{}' for all stations, '{"name": "Honolulu"}' for specific)

Optional Parameters:

• limit: Maximum number of results
• offset: Pagination offset

get_mesonet_data

Access real-time weather station measurements.

Optional Parameters:

• station_ids: Comma-separated station IDs
• start_date, end_date: Date range
• var_ids: Variable IDs to retrieve
• location: Geographic location
• limit, offset: Pagination
• join_metadata: Include station metadata (default: true)

generate_data_package

Create downloadable zip packages of climate data.

Required Parameters:

• email: Email address for delivery
• datatype: Climate data type

Optional Parameters:

• production, period, extent: Data specifications
• start_date, end_date: Date range
• files: Specific files to include
• zipName: Custom archive name

Usage Examples

Once configured in your AI assistant, you can use natural language queries like:

"Get rainfall data for Oahu on January 1st, 2023"

"Show me temperature time series for coordinates 21.3, -157.8 from 2022 to 2023"

"Find all weather stations in Hawaii"

"Create a data package with rainfall data for the Big Island in 2023"

The AI assistant will automatically use the appropriate HCDP MCP tools to fulfill these requests.

Supported Data Types

Climate Variables

• rainfall - Precipitation data
• temp_mean - Mean temperature
• temp_min - Minimum temperature
• temp_max - Maximum temperature
• rh - Relative humidity
• spi - Standardized Precipitation Index
• ndvi - Normalized Difference Vegetation Index
• ignition_probability - Fire weather data

Geographic Extents

• statewide - All Hawaiian islands
• oahu - Oahu island
• big_island - Hawaii (Big Island)
• maui - Maui island
• kauai - Kauai island
• molokai - Molokai island
• lanai - Lanai island

Locations

• hawaii - Main Hawaiian islands (default)
• american_samoa - American Samoa territory

Development

Setup Development Environment

# Install with development dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Format code
black hcdp_mcp_server/
ruff check hcdp_mcp_server/

# Run MCP server in development mode
python -m hcdp_mcp_server.server

Project Structure

hcdp-mcp/
├── hcdp_mcp_server/
│   ├── __init__.py
│   ├── server.py          # MCP server implementation
│   └── client.py          # HCDP API client
├── tests/                 # Test suite and example scripts
│   ├── test_*.py         # Unit tests
│   └── download_*.py     # Example download scripts
├── sample_data/          # Sample data files (.tiff, .csv)
├── .env.example          # Environment template (copy to .env)
├── .gitignore           # Git ignore patterns
├── mcp_config.json      # MCP server configuration example
├── pyproject.toml       # Project configuration
├── CLAUDE.md           # Claude Code instructions
└── README.md           # This file

Troubleshooting

Common Issues

1. API Token Issues

# Verify token is set
echo $HCDP_API_TOKEN

# Test token validity
curl -H "Authorization: Bearer $HCDP_API_TOKEN" https://api.hcdp.ikewai.org/stations?q={}&limit=1

2. MCP Server Not Found

# Verify installation
which hcdp-mcp-server

# Check if package is installed
pip list | grep hcdp-mcp-server

3. Connection Timeouts

• HCDP API responses can be slow for large datasets
• Consider using smaller date ranges or specific extents
• Check your internet connection

4. Invalid Parameters

• Ensure dates are in YYYY-MM-DD format
• Check that datatype values match supported climate variables
• Verify extent values are valid for your location

Getting Help

1. Check the HCDP API Documentation
2. Review the test files in the tests/ directory for usage examples
3. Check the example scripts in tests/download_*.py for practical usage
4. Review CLAUDE.md for development guidelines and commands
5. Enable debug logging by setting HCDP_DEBUG=true in your environment
6. File issues on the GitHub repository

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (pytest)
6. Format your code (black hcdp_mcp_server/)
7. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Hawaii Climate Data Portal for providing climate data access
• Model Context Protocol for the integration framework
• Anthropic for Claude and the MCP specification