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