README.md•6.96 kB
# ⚡ MCP Energy Server
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](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