Skip to content

🎉 v1.0.0 - First Production Release

Choose a tag to compare

View all tags
@ESJavadex ESJavadex released this 11 Oct 21:29
· 28 commits to main since this release
v1.0.0
7d8d891

🎉 REE MCP Server v1.0.0

First production-ready release! Access Spanish electricity data through Claude using natural language.

✨ What's Included

🛠️ MCP Tools (5)

Query Spain's electricity grid data with simple natural language:

  1. get_indicator_data - Fetch time-series data for any of 1,967+ indicators
  2. list_indicators - Browse all available REE indicators with metadata
  3. search_indicators - Find indicators by keyword (e.g., "solar", "precio", "demanda")
  4. get_demand_summary - Quick demand overview for any date
  5. get_generation_mix - Generation breakdown by source at specific times

📚 MCP Resources (2)

  • ree://indicators - Complete indicator catalog
  • ree://indicators/{id} - Individual indicator metadata

🏗️ Architecture Highlights

Built with industry best practices:

  • ✅ Domain-Driven Design (DDD) - 4 clean layers (Domain, Application, Infrastructure, Interface)
  • ✅ Clean Architecture - Dependencies point inward, domain has zero external deps
  • ✅ SOLID Principles - All 5 implemented throughout the codebase
  • ✅ Type Safety - 100% type-annotated, passes mypy strict mode
  • ✅ NO Mocking - Domain tests use pure functions (no mocks/stubs)
  • ✅ Comprehensive Testing - 59 tests covering all layers (unit, integration, e2e)

⚡ Production-Ready Features

  • 🔄 Automatic retry with exponential backoff for transient failures
  • 🛡️ Comprehensive error handling with domain-specific exceptions
  • ✅ Type-safe configuration using Pydantic Settings
  • ⚡ Async/await for optimal performance
  • 🔒 Context managers for proper resource cleanup
  • 📊 Structured logging with detailed error messages

📊 Data Access

Access 1,967+ electricity indicators including:

⚡ Real-Time Data (5-minute updates)

  • Electricity demand (real-time and forecasts)
  • Generation by source (nuclear, wind, solar, hydro, coal, gas)
  • Market prices (SPOT, PVPC rates)
  • CO₂ emissions tracking
  • International exchanges (imports/exports)

📈 Common Indicators

  • 1293 - Real Demand (Peninsular)
  • 2038 - Wind Generation (National)
  • 1295 - Solar PV (Peninsular)
  • 549 - Nuclear Generation
  • 600 - SPOT Market Price
  • 10355 - CO₂ Emissions

🚀 Installation & Setup

Quick Start (3 minutes)

# Clone and install
git clone https://github.com/ESJavadex/ree-mcp.git
cd ree-mcp
uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"

# Configure
cp .env.example .env
# Edit .env with your REE_API_TOKEN

# Add to Claude Code
./INSTALL_COMMAND.sh

Verify Installation

claude mcp list
# Should show: ree-mcp: ✓ Connected

💬 Example Usage

Open Claude Code and try:

  • "Show me the current electricity demand in Spain"
  • "What's the generation mix right now?"
  • "Compare solar vs wind generation today"
  • "Investigate what happened on April 28, 2025"
  • "Search for price indicators"

Claude will automatically use the REE MCP tools to fetch and analyze the data!

📚 Documentation

  • README.md - User guide with Quick Start and examples
  • CLAUDE.md - Developer guidance for contributing
  • API Reference - Common indicator IDs and usage patterns
  • Installation Script - Automated Claude Code setup

🎓 Learn More

Created by Javi Santos - AI & Robotics Specialist with published research in computer vision and LLM interpretability.

📚 Join La Escuela de IA

Learn AI without the fluff! Spanish AI learning community with real-world projects.
👉 skool.com/la-escuela-de-ia-9955

📺 YouTube Channel

AI tutorials, MCP servers, and LLM applications.
👉 @JavadexAI

🤝 Connect

🔧 Technical Details

Requirements:

  • Python 3.11+
  • REE API token (demo token included)

Dependencies:

  • fastmcp 0.2.0+
  • httpx 0.27.0+
  • pydantic 2.10.0+
  • pydantic-settings 2.6.0+

Development:

  • pytest, pytest-asyncio, pytest-cov
  • mypy (strict mode)
  • ruff (linting & formatting)

📄 License

This project is for educational and research purposes. The REE API is provided by Red Eléctrica de España.

🙏 Acknowledgments

  • REE (Red Eléctrica de España) for providing the eSios API
  • FastMCP for the excellent MCP framework
  • Anthropic for Claude and the Model Context Protocol

🐛 Issues & Support

Built with ❤️ using Domain-Driven Design and modern Python best practices

⭐ Star this repo if you find it useful!

Assets 2
Loading