# ⚡ MCP Energy Server

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![MCP](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io)

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](QUICKSTART.md) to get running in 5 minutes!

---

---

## 📋 Table of Contents

- [Features](#features)
- [Installation](#installation)
- [Configuration](#configuration)
- [Deployment Options](#deployment-options)
- [Available Tools](#available-tools)
- [Usage Examples](#usage-examples)
- [Development](#development)
- [API Documentation](#api-documentation)
- [License](#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

```bash
# 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)

```bash
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`

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

### Using with Other MCP Clients

The server can be started directly:

```bash
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:
```bash
python server.py
```

See [QUICKSTART.md](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](RENDER_DEPLOYMENT.md) for complete instructions.

**Run Web Server Locally:**
```bash
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](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:**
```json
{
  "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

```bash
pip install -e ".[dev]"
pytest
```

### Code Formatting

```bash
black .
ruff check .
```

## API Documentation

For more information about the EIA API and available data:
- [EIA API Documentation](https://www.eia.gov/opendata/)
- [EIA API Dashboard](https://www.eia.gov/opendata/browser/)

## 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