Kuksa Server

License Python

A Model Context Protocol (MCP) server that connects LLMs to vehicle data via the Eclipse Kuksa Databroker. Enables AI assistants to read and write vehicle signals using the standardized COVESA Vehicle Signal Specification (VSS).

Features

• Read signals — Get current or target values of any VSS signal
• Batch reads — Fetch multiple signals in a single call
• Write actuators — Set actuator targets or publish sensor readings
• Browse the VSS tree — List or count signals under any branch, with substring filtering
• Inspect types — Query data types for any signal path
• Server introspection — Name, version, signal count at startup
• Per-request logging — Every tool call logged with params, timing, and result summary
• Dual transport — stdio (default) and SSE (HTTP)
• OpenCode ready — Pre-configured opencode.jsonc for local and remote variants

Quick Start

1. Start a Kuksa Databroker

docker run -d --rm -p 55555:55555 --name kuksa-databroker \
  ghcr.io/eclipse-kuksa/kuksa-databroker:main --insecure

2. Install & Run

pip install kuksa-mcp-server
kuksa-mcp

Or from source:

git clone https://github.com/mikehaller/kuksa-mcp-server.git
cd kuksa-mcp-server
pip install -e ".[dev]"
kuksa-mcp

3. Configure your MCP client

{
  "mcpServers": {
    "kuksa": {
      "command": "kuksa-mcp"
    }
  }
}

{
  "mcpServers": {
    "kuksa-local": {
      "type": "local",
      "command": ["kuksa-mcp", "--log-file", "./kuksa-mcp.log"],
      "enabled": true,
      "timeout": 10000
    }
  }
}

{
  "mcpServers": {
    "kuksa-remote": {
      "type": "remote",
      "url": "http://127.0.0.1:8765/sse",
      "enabled": false,
      "timeout": 10000
    }
  }
}

OpenCode MCP Server Variants

The project ships with two entries in opencode.jsonc:

Start the remote variant manually:

kuksa-mcp --transport sse --host 0.0.0.0 --port 8765

CLI Reference

kuksa-mcp [options]

Options:
  --transport <stdio|sse>   Transport protocol (default: stdio)
  --host <ip>               Bind address for SSE (default: 127.0.0.1)
  --port <port>             Port for SSE (default: 8765)
  --kuksa-host <host>       Databroker host (overrides KUKSA_HOST env)
  --kuksa-port <port>       Databroker port (overrides KUKSA_PORT env)
  --log-file <path>         File path for request logging (also written to stderr)

Environment Variables

Tools

Resources

Startup Output

On startup the server prints a banner with version, databroker info, and catalog stats:

======================================================
  Kuksa Databroker MCP Server
  Version : 0.1.0
  Built   : 2026-06-24
======================================================
  Backend : databroker
  Address : 127.0.0.1:55555
  Version : 0.7.0-dev.0
  Status  : connected
  Signals : 1263 total
  Types   : ACTUATOR=643, ATTRIBUTE=130, SENSOR=490
======================================================

Every tool call is logged:

09:45:12 [INFO] Processing request of type ListToolsRequest
09:45:12 [INFO] Processing request of type CallToolRequest
09:45:12 [INFO] get_signal(args={'path': 'Vehicle.Speed'}) -> ok [0.023s]
09:45:15 [INFO] list_signals(args={'branch': 'Vehicle.Cabin', 'query': ''}) -> 490 results [0.045s]

Development

pip install -e ".[dev]"
pytest
kuksa-mcp --transport sse
python examples/local_test.py

Docker

The server is published as a Docker image on GitHub Container Registry:

docker pull ghcr.io/mikehaller/kuksa-mcp-server:latest

# Run with SSE transport
docker run --rm -p 8765:8765 \
  -e KUKSA_HOST=host.docker.internal \
  ghcr.io/mikehaller/kuksa-mcp-server:latest \
  --transport sse --host 0.0.0.0 --port 8765

The image uses a non-root kuksa user and is built from python:3.12-slim (~200 MB).

License

Apache 2.0 — see LICENSE.