Eclipse Ditto MCP Server

A Model Context Protocol (MCP) server for Eclipse Ditto — the open-source (EPL-2.0) digital twin framework. It exposes Ditto's HTTP API as MCP tools so an AI agent can manage devices ("things"), their attributes/features, policies, connections, and cluster admin — the full Ditto HTTP API surface.

Since Bosch IoT Things and other commercial IoT platforms are built on Ditto's open protocol, this server also works against those deployments — nothing in the code is vendor-specific.

Built with FastMCP.

Tools

Things

Attributes & Features

Messages

Policies

Connectivity & DevOps (require DITTO_DEVOPS_USERNAME/DITTO_DEVOPS_PASSWORD)

Ditto's Connections API and DevOps API (log levels, cluster config, piggyback commands) sit behind a separate "devops" Basic-auth realm on the gateway, independent of the policy-based auth used for things/policies.

Live events

Safety conventions

• Create vs. replace: every put_*/set_*/create_* tool defaults to overwrite=False, using Ditto's If-None-Match: * header so create-only is race-free (not a check-then-set). Pass overwrite=True to replace existing data.
• Deletes are confirm-gated: every delete_* tool requires confirm=True. There is no bulk/cascading delete.
• Not covered (deliberately): WoT Web-of-Things descriptor endpoints (/.well-known/wot, /devops/wot/*), and fine-grained policy sub-resources (subjects/{id}, resources/{path}, imports, token-integration actions) — whole-entry set_policy_entry/get_policy_entries covers the common case. Add these later if you need them.

Configuration

If both DITTO_BEARER_TOKEN and Basic auth credentials are set, the bearer token takes precedence. If neither is set, requests are sent unauthenticated (only works if your Ditto instance allows anonymous/pre-authenticated access).

Running locally

uv sync
export DITTO_BASE_URL=http://localhost:8080
export DITTO_USERNAME=ditto
export DITTO_PASSWORD=ditto
export DITTO_DEVOPS_USERNAME=devops    # only needed for connectivity/devops tools
export DITTO_DEVOPS_PASSWORD=foobar
uv run dittomcpserver.py

See mcp.json for ready-to-use client configs (stdio and Docker).

Testing against a real Ditto instance

This repo's design principles call for testing against a real instance rather than mocks. docker-compose.yml (adapted from Ditto's official example, trimmed to the services this connector needs) spins up a full local Ditto stack — MongoDB, the Ditto microservices, and an nginx front door with Basic auth.

docker compose up -d       # start Ditto on http://localhost:8080 (user: ditto / pass: ditto; devops: devops / foobar)
uv run pytest -v           # tests/conftest.py also starts/stops the stack automatically
docker compose down        # stop it manually if you started it yourself

The 47 tests cover every tool group (things, attributes/features, messages, policies, connectivity, devops, live events) against this real stack, including delete/confirm gating and create/overwrite gating.

A note on the live-events approximation

poll_thing_changes opens Ditto's SSE change feed for a bounded window instead of holding a persistent subscription (which doesn't map cleanly onto a single MCP tool call). Ditto's SSE stream sends periodic empty data: keepalive lines even when nothing has changed — the tool checks its deadline on every line received, including keepalives, so it reliably returns within duration_seconds regardless of how chatty or quiet the stream is.

License notes

docker-compose.yml and the files under docker/ are adapted from the Eclipse Ditto project (EPL-2.0) and are used here only to spin up a local test instance — they are not part of the MCP server itself.