Content
# Mercati Energetici MCP
A Model Context Protocol (MCP) server that exposes Italian electrical market data through a local server, providing seamless integration with Claude and other MCP-compatible applications.
## Overview
This project implements an MCP server that connects to the official APIs of **GME (Gestore dei Mercati Energetici)**, the operator of Italian energy markets. It enables programmatic access to real-time and historical data from the Italian electricity market, making it easy to integrate market data into AI-powered applications and workflows.
## Features
- **Real-time Market Data**: Access current prices, volumes, and market conditions from the Italian electricity market
- **Historical Data**: Query historical market data for analysis and reporting
- **MCP Integration**: Fully compatible with the Model Context Protocol for seamless integration with Claude and other tools
- **Local Server**: Run as a local MCP server for privacy and performance
- **Official APIs**: Built on the official GME (Gestore dei Mercati Energetici) APIs
## Prerequisites
- **Python**: 3.12 or higher
- **GME Account**: An approved account with GME to access their official APIs
- Contact GME to request API access: https://www.mercatoelettrico.org/
- You will need appropriate credentials and API keys
## Installation
This project uses **[uv](https://github.com/astral-sh/uv)** for fast, reliable Python package management.
### Prerequisites for Installation
- **uv**: Install from https://github.com/astral-sh/uv#installation
```bash
# macOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (with Powershell)
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
```
### Setup Steps
1. Clone the repository:
```bash
git clone <repository-url>
cd mercati-energetici-mcp
```
2. Install dependencies and create virtual environment:
```bash
uv sync
```
3. Activate the virtual environment:
```bash
source .venv/bin/activate # On Windows: .venv\Scripts\activate
```
That's it! `uv` automatically creates and manages the virtual environment in `.venv/`.
## Configuration
1. **Set up GME credentials**: Obtain your API credentials from GME
2. **Configure credentials**: Add your GME credentials to the environment or configuration file
- Create a `.env` file or set environment variables with your credentials
- Required environment variables:
- `GME_USERNAME`: Your GME username
- `GME_PASSWORD`: Your GME password
## Usage
### Running the MCP Server
This MCP server uses the **stdio protocol** for communication. Start the server:
```bash
python main.py
```
The server will initialize and wait for connections over stdin/stdout using the MCP protocol.
### Configuring with Claude Desktop
To use this MCP server with Claude Desktop, add it to your MCP configuration file:
**Mac/Linux**: `~/.config/claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
Example configuration:
```json
{
"mcpServers": {
"mercati-energetici": {
"command": "uv",
"args": [
"run",
"--directory",
"/path/to/mercati-energetici-mcp",
"python",
"main.py"
],
"env": {
"GME_USERNAME": "your-gme-username",
"GME_PASSWORD": "your-gme-password"
}
}
}
}
```
Replace `/path/to/mercati-energetici-mcp` with the absolute path to your installation, and add your GME credentials.
**Note**: Using `uv run` ensures the correct virtual environment and dependencies are used automatically.
### Using with Other MCP Clients
For other MCP-compatible applications, configure them to connect to this server using:
- **Protocol**: stdio
- **Command**: `uv run --directory /path/to/mercati-energetici-mcp python main.py`
- **Environment Variables**: Set `GME_USERNAME` and `GME_PASSWORD`
## Available MCP Tools
Once connected to the server, you can use the following tools to access Italian electricity market data:
### `get_prices`
Get electricity prices in €/MWh for a specific day and zone.
**Parameters:**
- `day` (optional): Date to query in format YYYYMMDD. Default is today.
- `zone` (optional): Market zone. One of: `CALA`, `CNOR`, `CSUD`, `NORD`, `PUN`, `SARD`, `SICI`, `SUD`. Default is `PUN` (whole Italy).
**Returns:** Dictionary mapping hours (0–23) to prices in €/MWh.
**Example use in Claude:**
> "Show me the electricity prices for Sicily (SICI) today"
>
> "What were the electricity prices on 20260410?"
---
### `get_volumes`
Get bought and sold volumes for a specific day and zone.
**Parameters:**
- `day` (optional): Date to query in format YYYYMMDD. Default is today.
- `zone` (optional): Market zone. One of: `CALA`, `CNOR`, `CSUD`, `NORD`, `SARD`, `SICI`, `SUD`, `TOTALE`. Default is `TOTALE` (whole Italy).
**Returns:** Pair of dictionaries mapping hours (0–23) to volumes (bought and sold) in MWh.
**Example use in Claude:**
> "How much electricity was traded in the northern zone yesterday?"
---
### `get_liquidity`
Get liquidity percentage of electricity markets for a specific day.
**Parameters:**
- `day` (optional): Date to query in format YYYYMMDD. Default is today.
**Returns:** Dictionary mapping hours (0–23) to liquidity percentage.
**Example use in Claude:**
> "What is the current market liquidity?"
---
### `daily_pun`
Get the average PUN (Prezzo Unico Nazionale - National Unique Price) for a specific day.
**Parameters:**
- `day` (optional): Date to query in format YYYYMMDD. Default is today.
**Returns:** Average PUN price in €/MWh.
**Example use in Claude:**
> "What is today's average electricity price (PUN)?"
>
> "Show me the PUN trend for the last week"
---
### `get_zones`
Get list of all available market zones with their descriptions.
**Parameters:** None
**Returns:** List of dictionaries with zone code and description. Includes:
- `PUN` - National Unique Price (whole Italy)
- `NORD` - North Italy
- `CNOR` - Central-North Italy
- `CSUD` - Central-South Italy
- `SUD` - South Italy
- `SICI` - Sicily
- `SARD` - Sardinia
- `CALA` - Calabria
- `TOTALE` - Total Italy (for volume queries only)
**Example use in Claude:**
> "What are all the available market zones?"
>
> "Show me the list of electrical market zones"
## Architecture
- Built with Python 3.12+
- Implements the Model Context Protocol specification
- Communicates with official GME APIs
- Designed for local deployment with minimal dependencies
## Project Structure
```
mercati-energetici-mcp/
├── main.py # MCP server entry point
├── pyproject.toml # Project configuration and dependencies
├── README.md # This file
└── .venv/ # Virtual environment (created during setup)
```
## API Capabilities
This MCP server can provide access to:
- **Day-Ahead Market (MGP)**: Electricity prices and volumes for the following day
- **Intraday Market (MI)**: Continuous trading market data
- **Balancing Market (MB)**: Reserve and balancing services data
- **Market Statistics**: Historical trends and analysis
- **Real-time Monitoring**: Current market conditions and status
## Requirements
- Official GME API access (requires approved account)
- Valid API credentials
- Internet connectivity to reach GME API endpoints
## Documentation
For more information about:
- **GME APIs**: Visit https://www.mercatoelettrico.org/
- **MCP Protocol**: Visit https://modelcontextprotocol.io/
- **Italian Energy Market**: Visit https://www.terna.it/
## Limitations
- Requires valid GME account and API credentials
- Subject to GME API rate limits and terms of service
- Designed for use within approved applications and workflows
## Support
For issues or questions related to:
- **API credentials**: Contact GME directly
- **MCP integration**: Refer to the Model Context Protocol documentation
- **This project**: Check the repository issues or documentation
## License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
## Disclaimer
This project is provided as-is for accessing publicly available market data through official APIs. Users are responsible for complying with GME's terms of service and all applicable Italian energy market regulations.
