OpenEI Utility Rates MCP Server

A Model Context Protocol (MCP) server that provides access to the OpenEI utility rates database. This server enables AI assistants and other MCP clients to search for utility rates, get detailed rate information, calculate bills, visualize rate schedules, and list utilities across the United States.

Features

• Search Utility Rates: Find rates by location, utility company, or rate classification
• Rate Details: Get comprehensive information about specific rate schedules with time-of-use schedules
• Bill Calculation: Calculate estimated utility bills based on real rate structures
• Schedule Visualization: ASCII art visualization of time-of-use rate schedules
• Utility Listings: Browse utility companies by geographic area
• Real Rate Data: Uses actual OpenEI API data with proper tiered pricing and demand charges
• Error Handling: Robust error handling with detailed error messages

Installation

NPX (Recommended)

The easiest way to use this MCP server is via npx:

npx openei-rates-mcp

Global Installation

npm install -g openei-rates-mcp

From Source

1. Clone this repository:

   git clone https://github.com/matthicks05/openei-rates-mcp.git
   cd openei-rates-mcp

2. Install dependencies:

   npm install

3. Build the project:

   npm run build

Configuration

API Key Setup

You need an OpenEI API key to use this server. Get one from NREL Developer Network.

Set the API key as an environment variable:

export OPENEI_API_KEY=YOUR_OPENEI_API_KEY

MCP Client Configuration

Add the server to your MCP client configuration. For Claude Desktop, add this to your claude_desktop_config.json:

Using NPX (Recommended)

{
  "mcpServers": {
    "openei-rates": {
      "command": "npx",
      "args": ["openei-rates-mcp"],
      "env": {
        "OPENEI_API_KEY": "YOUR_OPENEI_API_KEY"
      }
    }
  }
}

Using Global Installation

{
  "mcpServers": {
    "openei-rates": {
      "command": "openei-rates-mcp",
      "env": {
        "OPENEI_API_KEY": "YOUR_OPENEI_API_KEY"
      }
    }
  }
}

Using Local Installation

{
  "mcpServers": {
    "openei-rates": {
      "command": "node",
      "args": ["/path/to/openei-rates-mcp/dist/index.js"],
      "env": {
        "OPENEI_API_KEY": "YOUR_OPENEI_API_KEY"
      }
    }
  }
}

Claude Code CLI

If you're using Claude Code CLI, you can easily add this MCP server:

Using NPX (Recommended)

# Add the MCP server
claude mcp add openei-rates npx openei-rates-mcp

# Set your API key
claude mcp env openei-rates OPENEI_API_KEY YOUR_OPENEI_API_KEY

# Verify installation
claude mcp list
claude mcp test openei-rates

Using Global Installation

# Install globally first
npm install -g openei-rates-mcp

# Add to Claude Code
claude mcp add openei-rates openei-rates-mcp

# Set your API key
claude mcp env openei-rates OPENEI_API_KEY YOUR_OPENEI_API_KEY

# Verify installation
claude mcp list
claude mcp test openei-rates

Using Local Installation

# Clone and build first
git clone https://github.com/matthicks05/openei-rates-mcp.git
cd openei-rates-mcp
npm install && npm run build

# Add to Claude Code
claude mcp add openei-rates node "$(pwd)/dist/index.js"

# Set your API key
claude mcp env openei-rates OPENEI_API_KEY YOUR_OPENEI_API_KEY

# Verify installation
claude mcp list
claude mcp test openei-rates

Available Tools

1. search_utility_rates

Search for utility rates by various criteria.

Parameters:

• location (optional): ZIP code, city/state, or coordinates (lat,lng)
• utility_name (optional): Utility company name or partial name
• rate_type (optional): "residential", "commercial", or "industrial"
• sector (optional): Utility sector (e.g., "Electric", "Gas")
• limit (optional): Maximum results (1-500, default: 50)
• include_expired (optional): Include expired/inactive rates (default: false)
• sort_by_date (optional): Sort results by effective date, newest first (default: true)

Example:

{
  "location": "94102",
  "rate_type": "residential",
  "sector": "Electric",
  "limit": 10
}

2. get_rate_details

Get detailed information about a specific rate schedule.

Parameters:

• rate_id (required): Unique rate identifier from OpenEI
• include_tariff (optional): Include full tariff details (default: false)

Example:

{
  "rate_id": "5b75dadf5457a39c7e8b4567",
  "include_tariff": true
}

3. calculate_bill

Calculate estimated utility bill for given usage.

Parameters:

• rate_id (required): Rate schedule ID
• usage_kwh (required): Monthly usage in kilowatt-hours
• billing_month (optional): Month (1-12) for seasonal rates
• demand_kw (optional): Peak demand in kilowatts

Example:

{
  "rate_id": "5b75dadf5457a39c7e8b4567",
  "usage_kwh": 1000,
  "billing_month": 7,
  "demand_kw": 5
}

4. list_utilities

Get list of utility companies in a geographic area.

Parameters:

• state (optional): Two-letter state abbreviation (e.g., "CA")
• zip_code (optional): Five-digit ZIP code
• radius_miles (optional): Search radius in miles (1-100, default: 25)
• sector (optional): Filter by utility sector

Example:

{
  "state": "CA",
  "sector": "Electric"
}

5. visualize_rate_schedule

Generate ASCII visualization of rate schedule information including time-of-use schedules.

Parameters:

• rate_id (required): Unique rate identifier from OpenEI
• schedule_type (optional): "energy", "demand", or "both" (default: "both")
• format (optional): "table", "grid", or "compact" (default: "table")

Example:

{
  "rate_id": "539f6fcbec4f024411ecd2d1",
  "schedule_type": "both",
  "format": "table"
}

This tool provides detailed ASCII visualizations showing:

• Energy rate structure with tier pricing
• 12-month × 24-hour energy schedules (weekday/weekend)
• Demand charge structure and schedules
• Fixed charges breakdown
• Capacity limits
• Legend for interpreting schedule numbers

Development

Scripts

• npm run build - Compile TypeScript to JavaScript
• npm run dev - Watch mode for development
• npm start - Run the compiled server
• npm run clean - Remove build artifacts

Project Structure

src/
├── index.ts          # Entry point
├── server.ts         # MCP server implementation
├── openei-client.ts  # OpenEI API client
├── types.ts          # TypeScript definitions
└── tools/           # Individual tool implementations (future)

Error Handling

The server includes comprehensive error handling for:

• Validation Errors: Invalid parameters with detailed validation messages
• API Errors: OpenEI API failures with status codes and descriptions
• Network Errors: Connection timeouts and network issues
• Authentication Errors: Missing or invalid API keys

Caching

The server implements in-memory caching with a 1-hour TTL to improve performance and reduce API calls. Cache keys are generated based on the endpoint and parameters.

Troubleshooting

Common Issues

Rate Search Returns Old/Expired Rates

• The MCP automatically filters out expired rates by default (include_expired: false)
• Results are sorted by effective date with newest rates first (sort_by_date: true)
• If you need historical rates, set include_expired: true

Rate Details Not Found

• Verify the rate ID is correct from a search result
• Some rates may have been removed from the OpenEI database
• Rate IDs are case-sensitive

Bill Calculation Seems Incorrect

• The calculation uses real rate structures from OpenEI but may not include all utility-specific fees
• Complex time-of-use rates require proper tier and schedule interpretation
• Some rates may have minimum bills or other special conditions not captured

API Key Issues

• Ensure your OpenEI API key is valid and active
• Check that the environment variable OPENEI_API_KEY is properly set
• API keys can be obtained free from NREL Developer Network

Known Limitations

• Rate Calculation: Bill calculations use real rate structures but may not include all utility-specific fees, minimums, or special conditions
• Data Freshness: Rate data is cached for performance. Some information may be up to 1 hour old
• API Rate Limits: Respects OpenEI API rate limits (typically 1000 requests/hour)
• Search Coverage: Not all utilities may be fully represented in the OpenEI database

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE file for details.

Support

For issues and questions:

1. Check the OpenEI API documentation: https://apps.openei.org/services/doc/rest/util_rates/
2. Review the error messages for debugging information
3. Open an issue in this repository

API Reference

This server interfaces with the OpenEI Utility Rate Database API. For more information about the underlying data and API capabilities, visit:

• OpenEI API Documentation
• NREL Developer Network
• OpenEI Website

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.1.2] - 2025-09-24

Fixed

• Added missing sourceparent field to rate details response

[1.1.1] - 2025-09-24

Fixed

• Corrected filter handling in search_utility_rates tool
• Fixed filter logic in list_utilities tool

[1.1.0] - 2025-09-24

Added

• Initial public release of OpenEI Rates MCP server
• search_utility_rates tool for searching rates by location, utility, or sector
• get_rate_details tool for fetching detailed rate structures
• calculate_bill tool for estimating utility bills based on usage
• visualize_rate_schedule tool for ASCII visualization of rate schedules
• list_utilities tool for retrieving utility company lists
• Comprehensive documentation and build distribution
• In-memory caching with 1-hour TTL for performance
• Support for seasonal rate calculations and time-of-use schedules

Changed

• N/A

Fixed

• N/A

[1.0.0] - Initial Development

Added

• Initial project setup with TypeScript and MCP dependencies
• Core OpenEI API integration
• Basic MCP server implementation