MaStR MCP Server

MaStR MCP Server

适用于 Marktstammdatenregister（MaStR）的 MCP 服务——由 Bundesnetzagentur（德国联邦网络管理局）运营的德国能源市场主数据登记系统。让 Claude Desktop、Cowork 和 Claude Code 能够直接访问德国能源设施登记信息。

Deutsche Version / 德语版本

功能

21 个工具 — 14 个 SOAP 工具（需要凭据），7 个公共工具（始终可用）

工具	API	身份验证	说明
get_unit	SOAP	是	一次调用获取完整设施详情，以及 EEG、CHP、许可证和储能信息
search_power_generation_soap	SOAP	是	按条件搜索发电设施（全部 20 种能源类型、邮政编码、装机容量）
get_actor	SOAP	是	根据 MaStR 编号获取市场参与者详情
get_api_quota	SOAP	是	每日 API 配额（已用量 / 上限）
get_recent_changes	SOAP	是	增量同步：获取指定日期之后的变更（EEG、CHP、许可证、位置、储能）
search_power_consumption_soap	SOAP	是	按条件搜索用电设施（邮政编码、州、状态等）
search_gas_production_soap	SOAP	是	按条件搜索天然气生产设施（容量、邮政编码等）
search_gas_consumption_soap	SOAP	是	按条件搜索天然气用户（容量、邮政编码等）
search_actors_soap	SOAP	是	按条件搜索市场参与者（职能、角色、邮政编码等）
get_location	SOAP	是	位置详情，包括关联设施和电网接入点
get_catalog_values	SOAP	是	按类别 ID 获取目录／枚举值（法律形式、制造商等）
get_catalog_categories	SOAP	是	列出所有可用的目录类别
get_balancing_areas	SOAP	是	平衡区域（Y-EIC 代码、控制区域），可按配电网运营商筛选
get_grid_connection	SOAP	是	获取设施的电网接入点（电压等级、位置、同址设施）
search_power_generation_public	JSON	否	发电设施（27 个筛选键）
search_actors_public	JSON	否	市场参与者（23 个筛选键）
search_power_consumption_public	JSON	否	用电设施（29 个筛选键）
search_gas_production_public	JSON	否	天然气生产／储气设施（30 个筛选键）
search_gas_consumption_public	JSON	否	天然气用户（30 个筛选键）
search_grid_connections_public	JSON	否	电网接入点和位置（4 种类型，12–20 个筛选键）
get_local_time	SOAP	否	连接测试（始终可用）

10 种筛选运算符

后缀	运算符	说明
（无） / =	eq	等于（默认）
!=	neq	不等于
%	ct	包含
!%	nct	不包含
:	sw	以……开头
$	ew	以……结尾
>	gt	大于
<	lt	小于
?	null	为 NULL
! / !?	nn	不为 NULL

20 种能源类型

所有技术关键词均提供英文版本（德语别名也可使用）：

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。

无需凭据即可使用 7 个公共工具（搜索发电设施、用电设施、天然气生产、天然气消费、市场参与者、电网接入点，以及连接测试）。配置凭据后（.env），会额外注册 14 个 SOAP 工具（详情查询、条件搜索、目录、平衡区域等）。

安装

前置条件

• Python >= 3.10
• uv（推荐）或 pip
• MaStR Web 服务账户（SOAP API 工具可选）：https://www.marktstammdatenregister.de

步骤 1：克隆／复制项目

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

步骤 2：安装依赖

使用 uv（推荐）：

uv sync

使用 pip：

pip install -e .

第 3 步：在 .env 中存储凭据

服务器会自动从项目目录中的 .env 文件加载凭据（通过 python-dotenv）。这是推荐的做法。

cp .env.example .env
# Edit .env and fill in your values:
# MASTR_USER=SEM123456789012
# MASTR_TOKEN=your-webservice-token-540-chars

.env 已通过 .gitignore 排除，因此你的令牌不会被提交到代码仓库。

替代方式：你也可以将变量设为操作系统环境变量，或设在 Claude Desktop 配置的 env 块中——操作系统中的值优先。

第 4 步：测试

# Quick test
uv run mastr_mcp_server.py

# Or with the MCP Inspector
npx @modelcontextprotocol/inspector uv run mastr_mcp_server.py

Claude Desktop / Cowork 配置

打开 Claude Desktop 配置文件：

• Windows： %APPDATA%\Claude\claude_desktop_config.json
• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

如果 .env 位于项目目录中，可以省略 env 块：

{
  "mcpServers": {
    "mastr": {
      "command": "uv",
      "args": [
        "run",
        "--directory", "/path/to/mastr-mcp-server",
        "mastr_mcp_server.py"
      ]
    }
  }
}

重要： 请将 --directory 下的路径调整为你系统上的实际位置。

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"

使用示例

• “显示风力涡轮机 SEE966095906064 的详细信息” -> get_unit
• “查找邮政编码 49074 中的所有太阳能电站” -> search_power_generation_public({'tech': 'solar', 'postcode': '49074'})
• “邮政编码区域 23... 中，功率在 1200 到 3500 kW 之间的风力涡轮机” -> search_power_generation_public({'tech': 'wind', 'capacity>': 1200, 'capacity<': 3500, 'postcode:': '23'})
• “没有 EEG 编号的风力涡轮机” -> search_power_generation_public({'tech': 'wind', 'eeg_key?': ''})
• “邮政编码 49074 中的所有非风力机组” -> search_power_generation_public({'tech!=': '2497', 'postcode': '49074'})
• “Power-to-Gas 氢气电站” -> search_gas_production_public({'gas_technology': 'Power-to-Gas (Wasserstoff)'})
• “巴伐利亚的高压用电用户” -> search_power_consumption_public({'bundesland': 'Bayern', 'voltage_level': 'Hochspannung'})
• “使用 H-Gas 并发电的燃气用户” -> search_gas_consumption_public({'gas_quality': 'H-Gas', 'gas_for_power': True})
• “下萨克森州接入用户超过 100,000 户的配电网运营商” -> search_actors_public({'function': 'Stromnetzbetreiber', 'dso_large': True, 'bundesland': 'Niedersachsen'})
• “邮政编码 49074 中，电力发电的中压电网接入点” -> search_grid_connections_public('power_generation', {'postcode': '49074', 'voltage_level': 'Mittelspannung'})
• “使用 H-Gas 的燃气注入点” -> search_grid_connections_public('gas_production', {'gas_quality': 'H-Gas'})

项目结构

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

安全说明

• MaStR 令牌属于机密信息，应保存在 .env 中，绝不能提交到代码仓库。
• 服务器只执行读取操作（不进行注册或修改）
• 每日限额：每位用户 100,000 次 SOAP API 调用（公共 JSON 调用不限量）
• 仅接受 TLS 1.2 连接

许可证

MIT