bss-mcp 0.2.0

MCP server for the Basic Supply Service (BSS) — read-only debug tools

bss-mcp

An MCP server wrapping bssclient, exposing read-only BSS investigation-order data to AI assistants (e.g. Claude Desktop) for debugging.

Requires Python 3.11+.

Tools

Tool	Description
get_ermittlungsauftraege	List investigation orders (limit, offset; limit=0 uses the server default)
get_ermittlungsauftraege_by_malo	Investigation orders for a Marktlokation ID
get_aufgabe_stats	Task status statistics across all Aufgaben types
get_all_ermittlungsauftraege	Fetches all investigation orders by iterating pages (package_size controls page size, default 100)

Installation

pip install bss-mcp

For use with Claude Desktop or another MCP client, pipx installs the server as a standalone executable:

pipx install bss-mcp

Configuration

Set environment variables or place them in a .env file in the working directory from which the MCP server is launched (for Claude Desktop this is typically the user's home directory):

Variable	Required	Description
BSS_URL	Yes	Base URL of the BSS server, e.g. https://basicsupply.example.de/
BSS_AUTH_TYPE	No (default: basic)	basic or oauth
BSS_USER	If basic auth	Username
BSS_PASSWORD	If basic auth	Password
BSS_CLIENT_ID	If OAuth	OAuth client ID
BSS_CLIENT_SECRET	If OAuth	OAuth client secret
BSS_TOKEN_URL	If OAuth	Token endpoint URL

Usage

Run the server directly:

bss-mcp

Or add to your MCP client config (e.g. Claude Desktop). Use the full path to the executable if bss-mcp is not on the PATH seen by the client:

{
  "mcpServers": {
    "bss": {
      "command": "bss-mcp",
      "env": {
        "BSS_URL": "https://basicsupply.example.de/",
        "BSS_AUTH_TYPE": "basic",
        "BSS_USER": "...",
        "BSS_PASSWORD": "..."
      }
    }
  }
}

Development

This project follows the Hochfrequenz Python template — see it for general setup instructions (tox, CI, PyPI publishing).

tox -e tests       # run tests
tox -e type_check  # mypy --strict
tox -e linting     # pylint
tox -e coverage    # coverage ≥ 80 %
tox -e formatting  # black + isort