vnbdigital-mcp

MCP server for accessing the vnbdigital.de database of German distribution grid operators (Verteilnetzbetreiber, VNB).

Built on top of the vnbdigital-client library, which also ships a standalone CLI and can be used directly as a Python library in your own code. This repository adds an MCP interface on top, making the data available to AI assistants and agents via the Model Context Protocol (MCP).

Looking for the Python library or CLI? Head over to vnbdigital-client.

Tools

vnbdigital.de lookups

Tool	Description
`get_operator`	Basic master data for an operator by BDEW code or vnbdigital ID
`get_operator_details`	Full details including services, documents and logo
`get_operators`	Batch lookup for up to 50 IDs in a single call
`search`	Free-text search (postcode, name, city, region)
`search_by_coordinates`	Find responsible operators for a GPS coordinate (lat/lon)
`search_by_postcode`	Find responsible operators for a German postcode
`get_nsp_operator`	Low-voltage (Niederspannung) operator for a postcode or coordinate
`get_msp_operator`	Medium-voltage (Mittelspannung) operator for a postcode or coordinate

BDEW register lookups (bdew-codes.de)

Tool	Description
`bdew_lookup_by_company_code`	Look up a company by its 6–7 digit BDEW CompanyUId
`bdew_lookup_by_market_code`	Look up a company by a 13-digit BDEW market function code
`bdew_get_market_function_detail`	Fetch address and contact details for a market function entry

Note: Company names in the BDEW register do not always match those on vnbdigital.de. Use both sources together for cross-referencing.

Installation

Prerequisites

Python ≥ 3.12
uv

Install dependencies

uv sync

Start the server (development)

uv run vnbdigital-mcp
# or
uv run python -m vnbdigital_mcp.server

Test with MCP Inspector

uv run mcp dev src/vnbdigital_mcp/server.py

Configuration in VS Code / Claude Desktop

Add the server to your MCP configuration (.vscode/mcp.json or claude_desktop_config.json):

Install from PyPI (recommended):

{
  "servers": {
    "vnbdigital": {
      "command": "bash",
      "args": [
        "-l",
        "-c",
        "uvx vnbdigital-mcp"
      ]
    }
  }
}

Install from GitHub (latest unreleased):

{
  "servers": {
    "vnbdigital": {
      "command": "bash",
      "args": [
        "-l",
        "-c",
        "uvx --from git+https://github.com/the78mole/vnbdigital-mcp.git vnbdigital-mcp"
      ]
    }
  }
}

Local development (workspace checkout):

{
  "servers": {
    "vnbdigital": {
      "command": "bash",
      "args": [
        "-l",
        "-c",
        "uv --directory ${workspaceFolder} run vnbdigital-mcp"
      ]
    }
  }
}

Note: bash -l loads the login shell profile, which ensures uvx/uv are found in ~/.local/bin without any additional env configuration.

Environment Variables

Variable	Default	Description
`VNBDIGITAL_API_URL`	`https://www.vnbdigital.de/gateway/graphql`	GraphQL endpoint
`VNBDIGITAL_TIMEOUT`	`30`	HTTP timeout in seconds
`BDEW_LOOKUP_URL`	`https://bdew-codes.de`	Base URL for BDEW lookups

Example Queries

Operator by ID

Known example IDs:
- 179  → ESTW - Erlanger Stadtwerke AG
- 180  → Stadtwerke Eschwege GmbH
- 99   → Stadtwerke Bramsche GmbH

Operators for a location

get_nsp_operator and get_msp_operator accept either a 5-digit postcode or a "lat,lon" coordinate string:

get_nsp_operator("97816")              # by postcode
get_nsp_operator("49.998037,9.58033")  # by coordinates

BDEW lookup

bdew_lookup_by_company_code(660188)          # → A&A Stromallianz GmbH
bdew_lookup_by_market_code("9903445000000")  # → same company, one market function
bdew_get_market_function_detail(141)         # → address/contact for that market function

Local Development

# Set up project environment
uv sync

# Linting & formatting
uv run ruff format .
uv run ruff check --fix .

# Tests
uv run pytest

Related Projects

Project	Description
vnbdigital-client	Python client library this MCP server is built on. Provides typed access to the vnbdigital.de GraphQL API and the BDEW register.
vnbdigital.de	Official database of German distribution grid operators.
bdew-codes.de	BDEW market participant register with company and market function codes.

License

MIT

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

vnbdigital_mcp-0.8.6.tar.gz (94.3 kB view details)

Uploaded Aug 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

vnbdigital_mcp-0.8.6-py3-none-any.whl (8.3 kB view details)

Uploaded Aug 10, 2026 Python 3

File details

Details for the file vnbdigital_mcp-0.8.6.tar.gz.

File metadata

Download URL: vnbdigital_mcp-0.8.6.tar.gz
Upload date: Aug 10, 2026
Size: 94.3 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for vnbdigital_mcp-0.8.6.tar.gz
Algorithm	Hash digest
SHA256	`cbd8ea560f7b4cc4ab82c896aafdfd396b1bbc40a65dcf239b72a745068d0bf6`
MD5	`298a75f2b131277768144e3fb856ef8c`
BLAKE2b-256	`5fbdeedcdda7ab261f7355bcd44349e71f60ea5979577dcc9d69f9ee62ad26bf`

See more details on using hashes here.

Provenance

The following attestation bundles were made for vnbdigital_mcp-0.8.6.tar.gz:

Publisher: publish.yml on the78mole/vnbdigital-mcp

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: vnbdigital_mcp-0.8.6.tar.gz
- Subject digest: cbd8ea560f7b4cc4ab82c896aafdfd396b1bbc40a65dcf239b72a745068d0bf6
- Sigstore transparency entry: 2413682378
- Sigstore integration time: Aug 10, 2026
Source repository:
- Permalink: the78mole/vnbdigital-mcp@f90a1243a32cd2ff71026a762866c61b49da1db9
- Branch / Tag: refs/heads/main
- Owner: https://github.com/the78mole
- Access: public
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish.yml@f90a1243a32cd2ff71026a762866c61b49da1db9
- Trigger Event: push