⚡ MCP Energy Server

A Model Context Protocol (MCP) server that provides access to comprehensive energy data from the U.S. Energy Information Administration (EIA) API.

🚀 Quick Start: See QUICKSTART.md to get running in 5 minutes!

📋 Table of Contents

• Features

• Installation

• Configuration

• Deployment Options

• Available Tools

• Usage Examples

• Development

• API Documentation

• License

Features

This MCP server provides access to:

• Electricity Data: Generation, consumption, sales, and revenue data by state and sector

• Natural Gas Data: Production, consumption, prices, and storage information

• Petroleum Data: Production, consumption, imports, exports, prices, and stock levels

• Coal Data: Production, consumption, and pricing data

• Renewable Energy Data: Solar, wind, hydro, geothermal, and biomass generation

• CO2 Emissions: Emissions data by state and sector

• STEO Forecasts: Short-Term Energy Outlook projections

• International Data: Global energy statistics

Installation

From GitHub

# Clone the repository
git clone https://github.com/YOUR_USERNAME/mcp-energy.git
cd mcp-energy

# Install dependencies
pip install -e .

From PyPI (when published)

pip install mcp-energy

Configuration

Using with Claude Desktop

Add this to your Claude Desktop configuration file:

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

{
  "mcpServers": {
    "energy": {
      "command": "python",
      "args": ["-m", "server"],
      "cwd": "/path/to/mcp-energy"
    }
  }
}

Using with Other MCP Clients

The server can be started directly:

python server.py

It communicates via standard input/output using the MCP protocol.

Deployment Options

Option 1: MCP Server (Local/Desktop)

Run as a Model Context Protocol server for Claude Desktop:

python server.py

See QUICKSTART.md for setup instructions.

Option 2: Web API (Cloud Deployment)

Deploy as a REST API on platforms like Render.com:

Quick Deploy to Render.com:

1. Push code to GitHub

2. Connect GitHub repo to Render.com

3. Deploy with one click!

See RENDER_DEPLOYMENT.md for complete instructions.

Run Web Server Locally:

python server_web.py
# API available at http://localhost:10000
# Interactive docs at http://localhost:10000/docs

Web API Features:

• 🌐 REST API with JSON responses

• 📊 Interactive API documentation (Swagger UI)

• 🔄 CORS enabled for web applications

• 💚 Health check endpoint

• 🚀 Easy cloud deployment

For complete API documentation, see API_DOCUMENTATION.md

Available Tools

1. get_electricity_data

Get electricity generation, consumption, sales, or revenue data.

Parameters:

• frequency: "monthly", "quarterly", or "annual" (default: "monthly")

• data_type: "generation", "consumption", "sales", or "revenue" (default: "generation")

• facets: Optional filters (e.g., {"stateid": ["CA"], "sectorid": ["RES"]})

Example:

{
  "frequency": "monthly",
  "data_type": "generation",
  "facets": {
    "stateid": ["CA", "TX"],
    "sectorid": ["RES"]
  }
}

2. get_natural_gas_data

Get natural gas production, consumption, prices, or storage data.

Parameters:

• frequency: "monthly", "quarterly", or "annual" (default: "monthly")

• data_type: "production", "consumption", "prices", or "storage" (default: "consumption")

• facets: Optional filters

3. get_petroleum_data

Get petroleum production, consumption, imports, exports, prices, or stock data.

Parameters:

• frequency: "weekly", "monthly", "quarterly", or "annual" (default: "monthly")

• data_type: "production", "consumption", "imports", "exports", "prices", or "stocks" (default: "production")

• facets: Optional filters

4. get_coal_data

Get coal production, consumption, or price data.

Parameters:

• frequency: "monthly", "quarterly", or "annual" (default: "quarterly")

• data_type: "production", "consumption", or "prices" (default: "production")

• facets: Optional filters

5. get_renewable_data

Get renewable energy generation data.

Parameters:

• frequency: "monthly", "quarterly", or "annual" (default: "monthly")

• energy_source: "solar", "wind", "hydro", "geothermal", "biomass", or "all" (default: "all")

• facets: Optional filters

6. get_co2_emissions_data

Get CO2 emissions data by state and sector.

Parameters:

• frequency: "monthly" or "annual" (default: "annual")

• facets: Optional filters

7. get_steo_data

Get Short-Term Energy Outlook forecast data.

Parameters:

• frequency: "monthly" (default: "monthly")

• facets: Optional filters

8. get_international_energy_data

Get international energy statistics.

Parameters:

• frequency: "annual" (default: "annual")

• country: Country code or name

• facets: Optional filters

Usage Examples

Example 1: Get California Electricity Generation

Can you show me the latest monthly electricity generation data for California?

Example 2: Compare Natural Gas Prices

Compare natural gas prices between different states for the last quarter.

Example 3: Renewable Energy Trends

What are the solar energy generation trends in the US over the past year?

Example 4: CO2 Emissions Analysis

Show me the annual CO2 emissions data by sector for the most recent year available.

Development

Running Tests

pip install -e ".[dev]"
pytest

Code Formatting

black .
ruff check .

API Documentation

For more information about the EIA API and available data:

• EIA API Documentation

• EIA API Dashboard

License

MIT License - See LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions:

• Create an issue on GitHub

• Check the EIA API documentation for data availability

Changelog

Version 0.1.0 (Initial Release)

• Basic EIA API integration

• Support for electricity, natural gas, petroleum, coal, renewable, CO2, STEO, and international data

• MCP protocol implementation

• Claude Desktop integration