<div align="center">
# ⚡ MCP Energy Hub
### Real-Time Energy Grid Intelligence for Carbon-Aware AI
[](https://python.org)
[](https://modelcontextprotocol.io)
[](https://fastapi.tiangolo.com)
[](LICENSE)
[](https://github.com/karthikravva/MCP-Energy-Hub)
[](https://github.com/karthikravva/MCP-Energy-Hub/fork)
**Enterprise-grade MCP server providing real-time US power grid intelligence for carbon-aware AI compute scheduling**
[📖 Documentation](#-mcp-tools) • [🚀 Quick Start](#-quick-start) • [🤝 Contributing](CONTRIBUTING.md) • [📜 License](LICENSE)
</div>
---
## 🎯 The Problem
**AI compute is exploding, but the grid isn't always green.**
- Data centers consume **1-2% of global electricity** and growing rapidly
- AI training runs can emit as much CO2 as **5 cars over their lifetime**
- Most AI workloads run **without awareness of grid carbon intensity**
- Enterprises lack tools to **schedule compute when renewables are high**
## 💡 The Solution
**MCP Energy Hub** is an enterprise-grade MCP server that gives AI agents real-time visibility into the US power grid, enabling **carbon-aware compute scheduling**.
```
┌─────────────────────────────────────────────────────────────────┐
│ 🤖 AI Agent (Claude, etc.) │
│ │ │
│ ┌─────────▼─────────┐ │
│ │ MCP Protocol │ │
│ └─────────┬─────────┘ │
│ │ │
│ ┌───────────────▼───────────────┐ │
│ │ ⚡ MCP Energy Hub │ │
│ │ ┌─────────────────────────┐ │ │
│ │ │ 8 MCP Tools for Energy │ │ │
│ │ │ Grid Intelligence │ │ │
│ │ └─────────────────────────┘ │ │
│ └───────────────┬───────────────┘ │
│ │ │
│ ┌─────────────┬───────────┼───────────┬─────────────┐ │
│ ▼ ▼ ▼ ▼ ▼ │
│ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ ┌─────┐ │
│ │ERCOT│ │CAISO│ │ PJM │ │NYISO│ │MISO │ │
│ │Texas│ │Calif│ │ Mid │ │ NY │ │Midwest │
│ └─────┘ └─────┘ └─────┘ └─────┘ └─────┘ │
└─────────────────────────────────────────────────────────────────┘
```
---
## ✨ Key Features
| Feature | Description |
|---------|-------------|
| 🌍 **7 Grid Regions** | ERCOT, CAISO, PJM, NYISO, MISO, SPP, ISONE |
| ⚡ **Real-Time Data** | Live from EIA (US Energy Information Administration) |
| 🌱 **Carbon Intensity** | kg CO2/MWh for each region, updated hourly |
| 🔋 **Generation Mix** | Natural gas, coal, nuclear, wind, solar, hydro |
| 🏢 **Data Center Tracking** | Energy estimates, PUE, AI workload impact |
| 🎯 **Smart Scheduling** | Find the greenest region for your compute |
| 📊 **AI Impact KPIs** | Track AI's share of grid load |
| 🔌 **MCP Native** | Full Model Context Protocol support |
---
## 🛠️ MCP Tools
### 8 Tools for Energy Intelligence
| Tool | Description | Use Case |
|------|-------------|----------|
| `get_grid_realtime` | Real-time grid metrics | Monitor current load & generation |
| `get_grid_carbon` | Carbon intensity + recommendation | Carbon-aware scheduling |
| `get_grid_forecast` | Load & carbon forecast | Plan future workloads |
| `list_grid_regions` | Available grid regions | Discover coverage |
| `get_data_centers` | Data center info | Track facilities |
| `get_data_center_energy` | Energy consumption estimates | Audit energy use |
| `get_ai_impact` | AI compute KPIs | Measure AI's grid footprint |
| `get_best_region_for_compute` | **Find greenest region** | Optimize for carbon/cost |
### Example: Carbon-Aware Scheduling
```python
# AI Agent asks: "Where should I run this training job?"
result = mcp.call_tool("get_best_region_for_compute", {
"optimize_for": "carbon"
})
# Response:
{
"recommendation": "CAISO",
"reason": "Lowest carbon intensity at 180 kg CO2/MWh",
"rankings": [
{"region": "CAISO", "carbon": 180, "renewable_pct": 45},
{"region": "ERCOT", "carbon": 320, "renewable_pct": 28},
{"region": "PJM", "carbon": 420, "renewable_pct": 12}
]
}
```
---
## 🚀 Quick Start
### Prerequisites
- Python 3.11+
- [EIA API Key](https://www.eia.gov/opendata/register.php) (free)
### Installation
```bash
# Clone the repository
git clone https://github.com/your-username/mcp-energy-hub.git
cd mcp-energy-hub
# Create virtual environment
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# Install dependencies
pip install -r requirements.txt
# Configure environment
cp .env.example .env
# Edit .env and add your EIA_API_KEY
```
### Run the Server
```bash
# Start the FastAPI server
python -m uvicorn app.main:app --reload --port 8000
# Or run the standalone MCP server (for Claude Desktop)
python mcp_server.py
```
### Try the API
```bash
# Get carbon intensity for Texas grid
curl -X POST http://localhost:8000/mcp/tools/call \
-H "Content-Type: application/json" \
-d '{"name": "get_grid_carbon", "arguments": {"region_id": "ERCOT"}}'
```
### Example Response
```json
{
"success": true,
"result": {
"region_id": "ERCOT",
"timestamp": "2024-11-28T22:00:00Z",
"carbon_intensity_kg_per_mwh": 320.5,
"renewable_fraction_pct": 28.3,
"recommendation": "Good - Moderate carbon intensity"
}
}
```
### Connect to Claude Desktop
Add to your Claude Desktop MCP settings (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"energy-hub": {
"command": "python",
"args": ["/absolute/path/to/mcp-energy-hub/mcp_server.py"],
"env": {
"EIA_API_KEY": "your-api-key-here"
}
}
}
}
```
---
## 📊 API Endpoints
| Endpoint | Method | Description |
|----------|--------|-------------|
| `/docs` | GET | Interactive Swagger UI |
| `/mcp/info` | GET | MCP server information |
| `/mcp/tools` | GET | List all MCP tools |
| `/mcp/tools/call` | POST | Execute an MCP tool |
| `/grid/regions` | GET | List grid regions |
| `/grid/{region}/realtime` | GET | Real-time metrics |
| `/grid/{region}/carbon` | GET | Carbon intensity |
| `/health` | GET | Health check |
---
## 🏗️ Architecture
```
┌────────────────────────────────────────────────────────────┐
│ MCP Energy Hub │
├────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐ │
│ │ FastAPI │ │ MCP Server │ │ Data Ingestion │ │
│ │ REST API │ │ (8 Tools) │ │ (EIA Collector) │ │
│ └──────┬───────┘ └──────┬───────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └─────────────────┼────────────────────┘ │
│ │ │
│ ┌──────▼──────┐ │
│ │ SQLite DB │ │
│ │ Grid Metrics│ │
│ └─────────────┘ │
├────────────────────────────────────────────────────────────┤
│ External Data Sources │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ EIA │ │ ERCOT │ │ CAISO │ │ PJM │ │
│ │ API │ │ API │ │ API │ │ API │ │
│ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │
└────────────────────────────────────────────────────────────┘
```
---
## 🌍 Real-World Impact
### For Enterprises
- **Reduce carbon footprint** by scheduling AI workloads during high-renewable periods
- **Cost optimization** by running compute when energy prices are low
- **ESG reporting** with accurate AI energy consumption data
### For AI Developers
- **Carbon-aware training** - Train models when the grid is green
- **Transparent impact** - Know your model's carbon footprint
- **Automated scheduling** - Let AI agents make green decisions
### Potential Impact
- If 10% of AI workloads shifted to low-carbon periods: **~500,000 tons CO2/year saved**
- Real-time visibility enables **30-50% carbon reduction** for flexible workloads
---
## 🔧 Tech Stack
| Component | Technology |
|-----------|------------|
| **Backend** | FastAPI, Python 3.11 |
| **Database** | SQLite (HF) / PostgreSQL (Production) |
| **MCP Protocol** | Native implementation |
| **Data Source** | EIA Open Data API |
| **Deployment** | Docker, Hugging Face Spaces |
---
## 📁 Project Structure
```
mcp-energy-hub/
├── app/
│ ├── main.py # FastAPI application
│ ├── config.py # Configuration
│ ├── api/routes/ # REST endpoints
│ ├── mcp/ # MCP server implementation
│ │ ├── server.py # MCP protocol handler
│ │ ├── tools.py # Tool definitions
│ │ └── routes.py # HTTP MCP endpoints
│ ├── ingestion/ # Data collectors
│ │ └── eia_collector.py # EIA API integration
│ └── models/ # Database models
├── mcp_server.py # Standalone MCP server (stdio)
├── Dockerfile # HuggingFace deployment
└── README.md # This file
```
---
## � Docker Deployment
```bash
# Build the Docker image
docker build -t mcp-energy-hub .
# Run the container
docker run -p 8000:8000 -e EIA_API_KEY=your-key mcp-energy-hub
```
---
## 🧪 Testing
```bash
# Run tests
pytest
# Run with coverage
pytest --cov=app --cov-report=html
```
---
## 🤝 Contributing
Contributions are welcome! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request
---
## 🙏 Acknowledgments
- **[Anthropic](https://anthropic.com)** - For creating the MCP protocol
- **[EIA](https://www.eia.gov)** - For open energy data APIs
- **[FastAPI](https://fastapi.tiangolo.com)** - For the excellent web framework
---
## 📜 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
---
## 🔗 Links
- **� MCP Protocol**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
- **⚡ EIA Open Data**: [eia.gov/opendata](https://www.eia.gov/opendata/)
- **🐛 Report Issues**: [GitHub Issues](https://github.com/karthikravva/MCP-Energy-Hub/issues)
---
<div align="center">
**Made with ❤️ for sustainable AI**
*Helping AI compute become carbon-aware, one query at a time* ⚡🌱
⭐ Star this repo if you find it useful!
</div>
