MaStR MCP Server
MCP server for the German Marktstammdatenregister (MaStR) energy market register
Open source Open in the app JSON README (API)
About
MCP server for the German Marktstammdatenregister (MaStR) energy market register
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- ulircs
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 1.0.1
- Stars
- 6
- Forks
- 1
- Last push
- 2026-04-15T08:15:33Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 03:02:18
- Updated
- 2026-08-29 03:02:18
- Origin id
io.github.UliRCS/mastr-mcp-server
README
<!-- mcp-name: io.github.UliRCS/mastr-mcp-server -->
# MaStR MCP Server
An MCP server for the **Marktstammdatenregister** (MaStR) — the German energy market master data register operated by the Bundesnetzagentur (Federal Network Agency). Enables Claude Desktop, Cowork, and Claude Code to directly access the German energy plant registry.
[Deutsche Version / German version](README_de.md)
## Features
### 21 Tools — 14 SOAP (with credentials), 7 Public (always available)
| Tool | API | Auth | Description |
|---|---|---|---|
| `get_unit` | SOAP | Yes | Full unit details + EEG + CHP + permit + storage in one call |
| `search_power_generation_soap` | SOAP | Yes | Filtered search for power generation (all 20 energy carriers, postcode, capacity) |
| `get_actor` | SOAP | Yes | Market actor details by MaStR number |
| `get_api_quota` | SOAP | Yes | Daily API quota (used / limit) |
| `get_recent_changes` | SOAP | Yes | Delta sync: changes since date (EEG, CHP, permit, location, storage) |
| `search_power_consumption_soap` | SOAP | Yes | Filtered search for power consumers (postcode, state, status, etc.) |
| `search_gas_production_soap` | SOAP | Yes | Filtered search for gas production (capacity, postcode, etc.) |
| `search_gas_consumption_soap` | SOAP | Yes | Filtered search for gas consumers (capacity, postcode, etc.) |
| `search_actors_soap` | SOAP | Yes | Filtered search for market actors (function, role, postcode, etc.) |
| `get_location` | SOAP | Yes | Location details incl. linked units + grid connection points |
| `get_catalog_values` | SOAP | Yes | Catalog/enum values (legal form, manufacturer, etc.) by category ID |
| `get_catalog_categories` | SOAP | Yes | List all available catalog categories |
| `get_balancing_areas` | SOAP | Yes | Balancing areas (Y-EIC codes, control areas), optionally by DSO |
| `get_grid_connection` | SOAP | Yes | Grid connection points for a unit (voltage level, location, co-located units) |
| `search_power_generation_public` | JSON | No | Power generation units (27 filter keys) |
| `search_actors_public` | JSON | No | Market actors (23 filter keys) |
| `search_power_consumption_public` | JSON | No | Power consumption units (29 filter keys) |
| `search_gas_production_public` | JSON | No | Gas production / gas storage (30 filter keys) |
| `search_gas_consumption_public` | JSON | No | Gas consumption units (30 filter keys) |
| `search_grid_connections_public` | JSON | No | Grid connection points & locations (4 types, 12-20 filter keys) |
| `get_local_time` | SOAP | No | Connection test (always available) |
### 10 Filter Operators
| Suffix | Operator | Description |
|---|---|---|
| *(none)* / `=` | eq | Equal (default) |
| `!=` | neq | Not equal |
| `%` | ct | Contains |
| `!%` | nct | Does not contain |
| `:` | sw | Starts with |
| `$` | ew | Ends with |
| `>` | gt | Greater than |
| `<` | lt | Less than |
| `?` | null | Is NULL |
| `!` / `!?` | nn | Is NOT NULL |
### 20 Energy Carriers
All technology keywords are available in English (German aliases also work):
`wind`, `solar`, `biomass`, `hydro`, `storage`, `geo`, `mine_gas`, `sewage_sludge`,
`solar_thermal`, `pressure_relief_gas`/`pressure_relief_water`, `natural_gas`, `hard_coal`, `lignite`,
`mineral_oil`, `other_gases`, `waste`, `heat`, `hydrogen`, `nuclear`.
**Without credentials**, 7 public tools are available (search power generation, power consumption, gas production, gas consumption, market actors, grid connections + connection test). **With credentials** (.env), 14 additional SOAP tools are registered (detail queries, filtered searches, catalogs, balancing areas, etc.).
## Installation
### Prerequisites
- Python >= 3.10
- `uv` (recommended) or `pip`
- MaStR web service account (for SOAP API tools, optional): https://www.marktstammdatenregister.de
### Step 1: Clone / copy project
```bash
git clone https://github.com/UliRCS/mastr-mcp-server.git
cd mastr-mcp-server
```
### Step 2: Install dependencies
**With uv (recommended):**
```bash
uv sync
```
**With pip:**
```bash
pip install -e .
```
### Step 3: Store credentials in `.env`
The server automatically loads credentials from a `.env` file **in the project directory** (via `python-dotenv`). This is the recommended approach.
```bash
cp .env.example .env
# Edit .env and fill in your values:
# MASTR_USER=SEM123456789012
# MASTR_TOKEN=your-webservice-token-540-chars
```
`.env` is excluded via `.gitignore` — your token will not end up in the repo.
**Alternative**: You can also set the variables as OS environment variables or in the `env` block of the Claude Desktop config — OS values take precedence.
### Step 4: Test
```bash
# Quick test
uv run mastr_mcp_server.py
# Or with the MCP Inspector
npx @modelcontextprotocol/inspector uv run mastr_mcp_server.py
```
## Configuration for Claude Desktop / Cowork
Open the Claude Desktop configuration file:
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
If `.env` is in the project directory, you can omit the `env` block:
```json
{
"mcpServers": {
"mastr": {
"command": "uv",
"args": [
"run",
"--directory", "/path/to/mastr-mcp-server",
"mastr_mcp_server.py"
]
}
}
}
```
**Important:** Adjust the path under `--directory` to the actual location on your system.
## Configuration for Claude Code
```bash
claude mcp add mastr \
--command "uv" \
--args "run" "--directory" "/path/to/mastr-mcp-server" "mastr_mcp_server.py" \
--env "MASTR_USER=SOM123456789012" \
--env "MASTR_TOKEN=your-webservice-token"
```
## Usage Examples
- *"Show me the details of wind turbine SEE966095906064"*
-> `get_unit`
- *"Find all solar plants in postcode 49074"*
-> `search_power_generation_public({'tech': 'solar', 'postcode': '49074'})`
- *"Wind turbines between 1200 and 3500 kW in postcode area 23..."*
-> `search_power_generation_public({'tech': 'wind', 'capacity>': 1200, 'capacity<': 3500, 'postcode:': '23'})`
- *"Wind turbines WITHOUT EEG key"*
-> `search_power_generation_public({'tech': 'wind', 'eeg_key?': ''})`
- *"All non-wind units in postcode 49074"*
-> `search_power_generation_public({'tech!=': '2497', 'postcode': '49074'})`
- *"Power-to-Gas hydrogen plants"*
-> `search_gas_production_public({'gas_technology': 'Power-to-Gas (Wasserstoff)'})`
- *"High-voltage consumers in Bavaria"*
-> `search_power_consumption_public({'bundesland': 'Bayern', 'voltage_level': 'Hochspannung'})`
- *"Gas consumers with H-Gas that generate electricity"*
-> `search_gas_consumption_public({'gas_quality': 'H-Gas', 'gas_for_power': True})`
- *"DSOs with more than 100,000 connected customers in Lower Saxony"*
-> `search_actors_public({'function': 'Stromnetzbetreiber', 'dso_large': True, 'bundesland': 'Niedersachsen'})`
- *"Grid connection points for power generation in postcode 49074 at medium voltage"*
-> `search_grid_connections_public('power_generation', {'postcode': '49074', 'voltage_level': 'Mittelspannung'})`
- *"Gas feed-in points with H-Gas"*
-> `search_grid_connections_public('gas_production', {'gas_quality': 'H-Gas'})`
## Project Structure
```
mastr-mcp-server/
├── mastr_mcp_server.py # Entry point (imports package, starts server)
├── mastr_mcp/ # Main package
│ ├── __init__.py # Package init, conditional tool registration
│ ├── config.py # Constants, env vars, technology mappings
│ ├── serialization.py # SOAP->JSON, MS-AJAX date conversion
│ ├── client.py # SOAP client, HTTP fetch, retry helper
│ ├── filters.py # Filter builder, column mappings, dropdown loading
│ ├── server.py # FastMCP instance with instructions
│ ├── tools_soap.py # SOAP tools (14)
│ ├── tools_public.py # Public JSON tools (7)
│ └── resources.py # MCP Resources (4)
├── *_dropdowns.json # Dropdown ID mappings (5 files, from live API)
├── pyproject.toml # Dependencies and metadata
├── .env # Credentials (not in git)
└── .env.example # Credential template
```
## Security Notes
- The MaStR token is confidential — it belongs in `.env`, **never** in the repo.
- The server only performs read operations (no registrations or modifications)
- Daily limit: 100,000 SOAP API calls per user (public JSON is unlimited)
- Only TLS 1.2 connections are accepted
## License
MIT