Ree MCP

🚀 ⚡ REE MCP Server

Communicate with the Spanish power grid through Claude without technical knowledge. Ask Claude about electricity demand, generation, prices, and emissions in Spain using natural language, and it will handle all the technical details.

💡 Do you want to learn how to build projects like this? Join La Escuela de IA - a Spanish-speaking AI learning community where you can learn practical AI with real examples.

🚀 Quick Start

🎯 What Does This Server Do?

The Red Eléctrica de España (REE) manages the Spanish power grid 24/7 and publishes data every 5 minutes. This MCP server makes this data accessible through natural conversations with Claude.

The Power of Conversations with Real Data

By Javi Santos

Instead of writing Python scripts, imagine having conversations like this:

You: "Check what happened on April 28, 2025."

Claude: Analyzes grid data...

🚨 CRITICAL EVENT DETECTED - April 28, 2025, 12:35 PM

Massive Grid Collapse:

• 11,000 MW lost in 5 minutes (a 43% drop in capacity)
• The system instantly dropped from 25,184 MW to 14,185 MW
• Consistent with a cascading blackout scenario
• Recovery took over 10 hours

Analysis:

• 11:00 - 12:30: Stable system, no prior warnings
• 12:30 - 12:35: Instant catastrophic failure
• 12:35 - 13:35: Continuous degradation to a minimum of 9,635 MW
• Probable cause: Nuclear plant trip → Frequency collapse → Cascading

This would be one of the worst blackouts in modern Spanish history.

That's the power of this server. Investigate grid events, analyze renewable vs. fossil trends, correlate prices with demand, or track Spain's decarbonization - all through natural conversation. No API documentation. No scripts. Just ask.

📦 Installation (3 minutes)

1️⃣ Clone and Install

# Clone the repository
git clone https://github.com/ESJavadex/ree-mcp.git
cd ree-mcp

# Install uv (a fast Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or on macOS: brew install uv

# Create a virtual environment and install
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"

2️⃣ Configure API Token

# Copy the example file (includes a demo token)
cp .env.example .env

# Edit .env if you need your own token
# REE_API_TOKEN=your_token_here

Get a Token:

• Testing/Demo: Already included in .env.example
• Production: Email consultasios@ree.es

3️⃣ Add to Claude Code

# Run the installation script
./INSTALL_COMMAND.sh

# Verify
claude mcp list

You should see ree-mcp: ✓ Connected.

4️⃣ Ready! Start Asking

Open Claude Code and try:

• "Show me the current electricity demand in Spain."
• "What's the current generation mix?"
• "Compare today's solar and wind generation."

💻 Usage Examples

📊 Real-Time Operations

• "What's the current electricity demand in Spain?"
• "Show me the generation mix at noon."
• "How much energy did Spain export yesterday?"
• "Compare today's demand with last week's."
• "What's each power plant generating now? (nuclear, wind, solar...)"

🔍 Event Investigation and Analysis

• "Investigate what happened on April 28, 2025."
• "Was there any unusual grid activity last month?"
• "Find the day of peak demand this year and explain why."
• "Analyze the correlation between wind generation and prices."
• "Detect any abnormal patterns in the last week."
• "When was the last blackout or critical event?"

🌱 Renewable Energy and Emissions

• "How much solar energy is Spain generating?"
• "Compare this week's renewable and fossil generation."
• "What are the current CO₂ emissions? (gCO₂/kWh)"
• "Show me the wind energy trend in the last 30 days."
• "What percentage of the demand comes from renewables?"
• "When was the cleanest day (lowest CO₂) this month?"

💰 Price and Market Analysis

• "What's the current SPOT electricity price?"
• "Find the cheapest hours to consume electricity today."
• "Compare PVPC tariffs between weekdays and weekends."
• "When was electricity most expensive this month? Why?"
• "Show me the correlation between prices and renewable generation."

⚙️ Grid Stability and Storage

• "How's the current grid stability? (synchronous inertia vs. variable renewables)"
• "Are pumped storage plants being used to store energy?"
• "Show me the import/export flows with France and Portugal."
• "When does the grid pump water and when does it turbine?"

🔎 Data Discovery

• "Search for all indicators related to 'nuclear'."
• "What data is available on hydroelectric generation?"
• "Show me all price indicators."
• "List the available emissions and sustainability indicators."

📈 Comparisons and Trends

• "Compare this month's demand with the same month last year."
• "How has solar generation evolved in the last 6 months?"
• "Show me the net export/import balance for the last month."
• "When did we reach the historical peak of renewable generation?"

Claude automatically uses the right tools, fetches the data, and presents it in context with detailed analysis.

🎓 Learn to Build Projects Like This

This project was created by Javi Santos, an AI and Robotics Specialist with published research in:

• 🔬 Surgical sponge detection using Convolutional Neural Networks
• 🧠 Interpretability of Language Models in diverse knowledge scenarios

📚 La Escuela de IA

Do you want to learn AI without the hype and build projects like this?

Join La Escuela de IA - the Spanish AI learning community where you'll find:

• 🎯 Real-world practice - Build real AI projects, not toy examples
• 🇪🇸 Content in Spanish - Finally, AI education in your language
• 🛠️ Practical resources - Code, tutorials, and hands-on examples
• 👥 Active community - Learn with other Spanish-speaking AI enthusiasts

👉 Join La Escuela de IA

📺 YouTube Channel

Subscribe to JavadexAI for:

• 🎥 AI tutorials and project walkthroughs
• 💡 LLM applications and MCP servers
• 🚀 Real-world AI implementation strategies

🤝 Connect

• LinkedIn: Javi Santos
• YouTube: @JavadexAI
• La Escuela de IA: skool.com/la-escuela-de-ia-9955

🔧 Technical Details

✅ Production-Ready

• Automatic retries with exponential backoff
• Comprehensive error handling and validation
• Async/await for optimal performance
• 96 exhaustive tests with 90% coverage

🏗️ Robust Architecture

• Domain-Driven Design - Pure business logic
• Clean Architecture - Clear separation of responsibilities
• SOLID Principles - Maintainable and extensible code
• Type Safety - 100% typed with mypy in strict mode

📊 Complete Data

• Access to 1,967+ REE indicators
• Real-time data every 5 minutes
• Full historical data available
• 14 specialized MCP tools

🤝 Contribute

Contributions are welcome! See CLAUDE.md for a detailed developer guide.

This code follows strict architectural principles:

• Domain-Driven Design
• Clean Architecture
• SOLID Principles
• Exhaustive testing

💬 Support and Resources

Issues and Questions

• Server issues: Open an issue
• Questions about the REE API: consultasios@ree.es

Learn More

• 📚 La Escuela de IA - Learn AI in Spanish
• 📺 JavadexAI on YouTube
• 🤝 Javi Santos on LinkedIn

Resources

• REE eSios API: https://api.esios.ree.es/
• FastMCP: https://github.com/jlowin/fastmcp
• Model Context Protocol: https://modelcontextprotocol.io/

📄 License

MIT License with Disclaimer - See the LICENSE file for full details.

⚠️ Important Note

This software is provided "as is" without warranties. Use it at your own risk.