Skip to main content
Glama
mastr-mcp-server

mastr-mcp-server

by UliRCS

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

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.).

Related MCP server: strompreis-mcp

Installation

Prerequisites

Step 1: Clone / copy project

git clone https://github.com/UliRCS/mastr-mcp-server.git
cd mastr-mcp-server

Step 2: Install dependencies

With uv (recommended):

uv sync

With pip:

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.

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

# 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:

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

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

Available Tools

7 tools
get_local_timeA

Connection test — returns current server time if MaStR SOAP service is reachable.

No authentication required. Use this to verify network connectivity.

Inputs: no named parameters.

search_actors_publicA

Search market actors (Marktakteure) — no auth required.

Find energy market participants: DSOs (Netzbetreiber), generators, suppliers, traders, and more. 23 filter keys for name, function, role, location, status, and DSO flags (large DSO, closed distribution network).

NOTE: MaStR stores '&' as fullwidth U+FF06 in company names. Use 'name%' with a substring without '&' for reliable company name searches.

Inputs: filters (required), page, page_size.

search_gas_consumption_publicA

Search gas consumption units (Gasverbrauch) — no auth required.

Find registered gas consumers. 30 filter keys covering identification, location, dates, gas quality (H-Gas/L-Gas), maximum capacity, and whether the gas is used for power generation (gas_for_power flag).

Inputs: filters (required), page, page_size.

search_gas_production_publicA

Search gas production and storage units (Gaserzeugung) — no auth required.

Find biogas plants, Power-to-Gas (hydrogen/methane), LNG terminals, fossil gas producers, and gas storage units. 30 filter keys including gas technology and unit type (producer vs. storage).

Inputs: filters (required), page, page_size.

search_grid_connections_publicA

Search grid connection points and locations (Netzanschlusspunkte) — no auth required.

Find where units connect to the grid. Returns location data, grid connection points, linked units, DSO info, and network parameters. Supports 4 connection types: power generation/consumption and gas production/consumption. Power types include voltage level, control area, and balancing area. Gas types include gas quality and market area.

For grid connection details of a specific unit, use get_grid_connection (SOAP).

Inputs: filters (required), connection_type (required), page, page_size.

search_power_consumption_publicA

Search power consumption units (Stromverbrauch) — no auth required.

Find large electricity consumers registered in MaStR. 29 filter keys covering identification, location, dates, voltage level, and DSO checks.

Use this when searching for electricity consumers (not generators).

Inputs: filters (required), page, page_size.

search_power_generation_publicA

Search power generation units (Stromerzeugung) — no auth required.

The primary tool for finding wind turbines, solar panels, biomass plants, hydro, storage, gas turbines, nuclear plants, etc. in the MaStR register. Supports all 20 energy carriers with 27 filter keys and 10 operators.

Use this as the default search tool for power generation questions. For full unit details after finding a MaStR number, use get_unit (SOAP).

Inputs: filters (required), page, page_size.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct entity type (power generation, actors, consumption, gas production, gas consumption, grid connections) and the connection test. No overlap in purpose; descriptions clearly differentiate them.

    Naming Consistency4/5

    All search tools follow a consistent 'search_{domain}_public' pattern. The lone 'get_local_time' breaks the pattern but serves a distinct health-check purpose, so the deviation is minor and acceptable.

    Tool Count5/5

    With 7 tools, the set covers the major queryable entities in MaStR without being excessive. Each tool serves a clear role, and the count is appropriate for the server's scope.

    Completeness3/5

    The tools cover searching for all main entity types, but lack retrieval of full details (e.g., get_unit, get_grid_connection) after search, requiring external SOAP calls. This is a notable gap for a complete workflow.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      F
      maintenance
      One-call Australian energy-market plumbing via AEMO — cited, structured responses for market data and analysis, not a data broker.
      5
      196 PyPI
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP server for querying ENTSO-E Transparency Platform data including actual load, generation per type, cross-border flows, and installed capacity.
      84 npm
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      MCP server for Swiss electricity data from three official sources — production mix, consumption forecast, storage-lake fill, consumer price index, tariffs per municipality, and dataset discovery. Zero authentication.
      12
      52 PyPI
      MIT