How do I use MCP Energy Hub?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@MCP Energy Hub Find the greenest grid region to schedule my AI compute job right now." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

⚡ MCP Energy Hub

Real-Time Energy Grid Intelligence for Carbon-Aware AI

GitHub Stars GitHub Forks

Enterprise-grade MCP server providing real-time US power grid intelligence for carbon-aware AI compute scheduling

📖 Documentation • 🚀 Quick Start • 🤝 Contributing • 📜 License

🎯 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

# 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 (free)

Installation

# 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

# 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

# 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

{
  "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):

{
  "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

# 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

# Run tests
pytest

# Run with coverage
pytest --cov=app --cov-report=html

🤝 Contributing

Contributions are welcome! Please see our Contributing Guidelines for details.

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

🙏 Acknowledgments

Anthropic - For creating the MCP protocol
EIA - For open energy data APIs
FastAPI - For the excellent web framework

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

� MCP Protocol: modelcontextprotocol.io
⚡ EIA Open Data: eia.gov/opendata
🐛 Report Issues: GitHub Issues

Made with ❤️ for sustainable AI

Helping AI compute become carbon-aware, one query at a time ⚡🌱

⭐ Star this repo if you find it useful!

MCP Energy Hub