bosch-smart-home-camera-mcp 1.4.0

Model Context Protocol server for Bosch Smart Home cameras

Bosch Smart Home Camera — MCP Server

Model Context Protocol (MCP) server that exposes the Bosch Smart Home Camera cloud API as MCP tools. Drop-in for Claude Code, Claude Desktop, and any MCP-compatible client. Reuses the proven reverse-engineered API client from the sister Python CLI tool.

Status: v1.3.6 — 9 bug fixes from live audit 2026-05-24 (camera list always live from cloud, Gen1/Gen2 hw_version, UUID resolution, events field mapping, audio camelCase, intrusion Gen2 gate, error codes, snapshot timestamp). 16 tools + 3 resources + 2 prompts, stdio/SSE/streamable-HTTP, pipx/uvx-installable

Disclaimer

This project is an independent, community-developed tool. It is not affiliated with, endorsed by, sponsored by, or in any way officially connected to Robert Bosch GmbH, Bosch Smart Home GmbH, or any of their subsidiaries or affiliates. "Bosch", "Bosch Smart Home", and related names and logos are registered trademarks of Robert Bosch GmbH.

The tool communicates with a reverse-engineered, undocumented, unofficial API. Provided "as is", without warranty of any kind. Use entirely at your own risk.

Why a separate MCP server?

The sister projects target different runtimes:

Project	Version	Runtime	User-facing surface
HA Integration	v12.8.4	Home Assistant	UI entities, Lovelace card, automations
Python CLI	v10.7.7	terminal	bosch_camera ... commands
ioBroker Adapter	v0.7.14	ioBroker	datapoints, JSON-config admin UI
Node-RED nodes	v0.1.0-alpha	Node-RED	flow nodes for automation pipelines
MCP Server (this repo)	v1.3.6	Claude clients	MCP tools callable from LLMs

LLM use-cases the existing sisters don't cover:

• "Take a snapshot of the garden camera and describe what you see."
• "What was the last motion event on the terrace, and at what time?"
• "Enable privacy mode on the indoor camera until 22:00, then disable it."
• "Pan the 360° camera to the left and grab a snapshot."
• "Summarise today's motion events across all cameras."

These flows require an LLM in the loop — which is exactly what MCP is for.

Integration Comparison

The Bosch Smart Home Camera reverse-engineered API is exposed via four sibling projects. Pick the one that fits your platform.

Feature	Home Assistant Integration	Python CLI Tool	ioBroker Adapter	MCP Server
Maturity	v13.0+ — HA Quality Scale Platinum	v10.7+ stable (Mini-NVR BETA)	v0.7+ beta	v1.3+ stable · PyPI
Platform	Home Assistant (HACS)	Standalone Python 3.10+ CLI	ioBroker (npm)	Python 3.10+ · pipx / uvx · stdio + streamable-HTTP for MCP clients (Claude Desktop, Claude Code, custom)
Login	OAuth2 PKCE (browser)	OAuth2 PKCE (browser)	OAuth2 PKCE (browser)	OAuth2 PKCE (browser, one-time)
Snapshots	✅ Native Camera.image	✅ snapshot command	✅ File-store + base64 DP	✅ bosch_camera_snapshot (LAN-only)
Live RTSP stream (LAN)	✅ via HA Stream component	✅ ffmpeg/RTSPS output	✅ TLS proxy → local RTSP	✅ bosch_camera_stream_url (LAN-only, no cloud relay)
WebRTC (sub-second latency)	✅ via integrated go2rtc	✅ (v10.6.0) live --webrtc	❌	❌
Dual-stream URL (main + sub)	✅ sensor.bosch_<n>_stream_url + _sub (v12.4.0, opt-in per cam)	✅ info shows both · live --sub (v10.5.0)	✅ stream_url + stream_url_sub (v0.5.3 experimental)	✅ via bosch_camera_info (verbose URLs)
External recorder (BlueIris, Frigate)	✅ via go2rtc	✅ stdout pipe	✅ Digest-creds URL + LAN bind option	✅ URL returned, hand off to ffmpeg / go2rtc downstream
Privacy mode	✅ switch entity	✅ command	✅ DP	✅ bosch_camera_privacy_set (LAN-fallback via prefer_local)
Front spotlight (Gen1/Gen2)	✅ light entity	✅ command	✅ DP	✅ bosch_camera_light_set (LAN-fallback)
RGB wallwasher (Gen2 Outdoor II)	✅ light w/ RGB	✅ command	✅ color + brightness DPs	❌ (on/off only — RGB not exposed)
Panic-alarm siren	✅ button entity (Gen2 Indoor II)	✅ command (Gen1 360° only)	✅ DP	❌ (intentionally not exposed)
Image rotation 180°	✅ switch	✅ flag	✅ DP	❌
Motion / person / audio events	✅ FCM push + polling fallback	✅ event-watch command	✅ FCM push + polling fallback	✅ bosch_camera_events (on-demand pull)
Motion edge-trigger state	✅ binary_sensor.motion	n/a	✅ motion_active DP (v0.5.3)	n/a (request-response, no subscription)
Auto-snapshot on motion	✅ refreshes Camera entity	n/a	✅ writes last_event_image base64 (v0.5.3)	n/a (no background loop)
Synthetic motion trigger (external sensor)	✅ service	n/a	✅ DP	❌
Cloud clip download (history ~30 d)	✅ via Media Browser	❌	❌ (parked — no community request yet)	❌ (intentionally not exposed — large payloads)
Mini-NVR (motion-triggered local recording)	✅ (v11.2.0 BETA)	✅ (v10.7.0 BETA)	❌	❌
SMB / NAS clip upload	✅	✅ (v10.7.0 BETA)	❌	❌
Camera sharing (friends)	❌	✅ command	❌	❌ (intentionally not exposed — needs user-driven flow)
Pan / tilt (360° Gen1)	✅ services	✅ command	✅ pan_position DP	✅ bosch_camera_pan
Named pan presets (home / left / right / back-left / back-right)	✅ opt-in select entity	✅ pan --preset flag	✅ pan_preset DP	✅ bosch_camera_pan preset=
Two-way audio / intercom	❌	✅ command	❌	❌ (intentionally not exposed — timing-sensitive)
Webhook delivery on events	✅ service + opt-in options	✅ watch --webhook URL	✅ via MQTT bridge	❌ (request-response model)
MQTT event bridge (motion / audio / person)	n/a (HA event bus native)	n/a (single-run)	✅ admin-config	n/a
Apple HomeKit (via HA Core bridge)	✅ documented	n/a	n/a	n/a
Snapshot scheduler / time-lapse	✅ examples/ YAML	✅ cron + ffmpeg examples	✅ Blockly example	n/a
Custom Lovelace card	✅ 2 cards (single + grid)	n/a	n/a	n/a
ioBroker VIS dashboard	n/a	n/a	✅ via snapshot_path + stream_url + VIS-2 widget (alpha)	n/a
Cloud-relay REMOTE fallback	✅ auto-switch when LAN unreachable	✅ remote mode	❌ (LOCAL-only by design)	❌ (media LAN-only; status/events via cloud)
Browser-based admin / config UI	✅ HA Config Flow	n/a (CLI)	✅ JSON-config tabs	n/a (LLM-mediated; config via CLI / MCP client)
UI languages	EN · DE · FR · ES · IT · NL · PL · PT · RU · UK · ZH-Hans (v12.4.0)	EN · DE · FR · ES · IT · NL · PL · PT · RU · UK · ZH-Hans (v10.3.0)	EN · DE · FR · ES · IT · NL · PL · PT · RU · UK · ZH-CN	n/a (no UI — LLM is the front-end)

Legend: ✅ supported · ❌ not supported / not planned · n/a not applicable for this platform.

All four projects share the same reverse-engineered Cloud API + RCP protocol research, but evolve independently. The Home Assistant integration is the most feature-complete reference implementation; the Python CLI is the lowest-level / scriptable surface; the ioBroker adapter targets VIS dashboards and Blockly automations; the MCP server exposes a curated, LAN-first tool surface to MCP clients (Claude Desktop, Claude Code, custom) for natural-language camera control.

---

Architecture

┌─────────────────────────┐      stdio / SSE / streamable HTTP      ┌─────────────────────────┐
│  Claude Code / Desktop  │ ←─────────────────────────────────────→ │  bosch-smart-home-      │
│  (MCP host)             │             MCP protocol                │  camera-mcp server      │
└─────────────────────────┘                                         └────────────┬────────────┘
                                                                                 │
                                                              imports / shared API client
                                                                                 │
                                                                                 ▼
                                                                  ┌─────────────────────────┐
                                                                  │ bosch_camera.py         │
                                                                  │ (sister Python CLI tool)│
                                                                  └────────────┬────────────┘
                                                                               │ HTTPS (OAuth2 PKCE)
                                                                               ▼
                                                                  ┌─────────────────────────┐
                                                                  │ residential.cbs.bosch-  │
                                                                  │ security.com (cloud)    │
                                                                  └─────────────────────────┘

The MCP server is a thin wrapper around the Python CLI's API layer. It does not re-implement OAuth, token refresh, FCM push, RTSP, or RCP — it imports them.

LAN-fallback tool routing

flowchart LR
    Agent["LLM / Claude Code"] -->|tool call| MCP[MCP Server]
    MCP -->|prefer_local=False| Cloud[Bosch CBS API]
    MCP -->|prefer_local=True| RCP["Camera LAN RCP\n192.168.x.y:443\nHTTPS Digest"]
    RCP -->|success| Done["return {status, method: local}"]
    RCP -->|fail| Cloud
    Cloud --> Done2["return {status, method: cloud}"]
    style RCP fill:#d4f1c4,color:#000
    style Cloud fill:#dce8fb,color:#000

bosch_camera_lan_ping tool flow

sequenceDiagram
    participant Agent as LLM Agent
    participant Tool as bosch_camera_lan_ping
    participant TCP as TCP connect :443

    Agent->>Tool: {camera_name: "Outdoor"}
    Tool->>Tool: resolve LAN IP from bosch_config.json
    Tool->>TCP: connect 192.168.x.y:443 (1.5 s timeout)
    TCP-->>Tool: connected / timeout
    Tool-->>Agent: {reachable: true, ip: "...", latency_ms: 12}

MCP tools (16 total, v1.3.6)

Tool	Description	Returns
bosch_camera_list	List all configured cameras	array of {id, name, model, hw_version, status}
bosch_camera_status	Get online/offline + privacy state for one camera	{name, status, privacy_mode, light_on, last_event_at}
bosch_camera_snapshot	LAN-only JPEG capture (no cloud) — HTTP Digest to camera IP	{path, method, timestamp}
bosch_camera_stream_url	LAN-only RTSPS stream URL (no cloud relay) — consumable by ffmpeg/VLC/go2rtc	{camera, rtsps_url, note}
bosch_camera_events	List recent motion/person/audio events	array of {event_id, type, timestamp, has_clip}
bosch_camera_privacy_set	Turn privacy mode on/off; prefer_local=True routes to LAN RCP first	{name, status, privacy_mode, ...}
bosch_camera_light_set	Turn spotlight on/off; prefer_local=True routes to LAN RCP first	{name, status, light_on, ...}
bosch_camera_pan	Pan the 360° camera; preset: home (0°) / left (-60°) / right (+60°) / back-left (-120°) / back-right (+120°)	{camera, direction, preset?}
bosch_camera_notifications_set	Toggle push notifications	{camera, notifications_on}
bosch_camera_lan_ping	TCP-probe a camera on LAN port 443 (1.5 s timeout)	{reachable, ip, latency_ms}
bosch_camera_maintenance_status	Fetch current cloud maintenance announcement from community RSS feed	{state, title, link, pub_date, summary, …, recommended_action}
bosch_camera_audio_get	Get microphone level, speaker level, intercom flag (Gen2 only)	{microphone_level, speaker_level, intercom_enabled}
bosch_camera_audio_set	Set microphone level and/or speaker level 0-100 (Gen2 only)	{microphone_level, speaker_level, intercom_enabled}
bosch_camera_intrusion_get	Get intrusion detection config: mode, sensitivity 0-7, distance 1-10 m (Gen2 only)	{mode, sensitivity, distance}
bosch_camera_intrusion_set	Update intrusion detection mode/sensitivity/distance (Gen2 only)	{mode, sensitivity, distance}
bosch_camera_wifi	Get WiFi RSSI, SSID, and derived signal quality 0-100 %	{rssi, ssid, signal_strength}
bosch_camera_mjpeg_snapshot	Direct LAN MJPEG snapshot via RTSP inst=3 (Gen2 only, ffmpeg, no cloud roundtrip)	{path, method, timestamp, camera}
bosch_camera_onvif_scopes	Read ONVIF device scopes from camera LAN RCP 0x0a98 (Gen2 only)	{name, hardware, profiles, raw_scopes}
bosch_camera_rcp_version	Read RCP library version from camera LAN opcodes 0xff00 + 0xff04	{primary, secondary, raw_primary_hex, raw_secondary_hex}
bosch_camera_feature_flags	Fetch account-level Bosch cloud feature flags (no camera param)	{FLAG_NAME: bool, ...}

Tools intentionally NOT exposed to LLMs (write-risky / time-consuming):

• Token refresh (handled silently by the underlying client)
• Camera sharing / friends (require user-driven flow)
• Cloud clip download (large payloads)
• Audio intercom (timing-sensitive)

Reliability — transparent credential rotation

LAN-RCP tools (bosch_camera_privacy_set, bosch_camera_light_set, bosch_camera_pan with prefer_local=True) automatically retry once on HTTP 401 after re-fetching fresh Digest credentials from bosch_config.json. No user-visible API change — the retry is silent and the tool result is identical whether or not rotation was needed. This eliminates cold-start failures when the cached Digest nonce has expired.

MCP resources

Resource URI	Description
bosch://cameras	JSON list of all cameras (id, name, model, status, firmware, mac, description)
bosch://cameras/{name}/snapshot.jpg	Latest cached JPEG, or fresh capture if cache empty
bosch://cameras/{name}/events	Last 50 events (motion, person, audio) as JSON list

bosch://cameras is a static resource. The {name} variants are resource templates.

MCP prompts

Prompt	Arguments	Description
daily-camera-summary	hours: int = 24	Multi-step report: events per camera, type breakdown, time distribution, anomaly highlights
pre-leave-check	(none)	Snapshot every camera, describe scene, flag anomalies, recommend indoor privacy mode

Privacy stance — media operations are LAN-only

Snapshots and stream URLs go directly from the MCP host to the camera over the LAN — no Bosch cloud relay. The remaining tools (status, events, privacy/light/pan/notifications) still use the cloud because no local API is currently exposed for those endpoints.

Tool	Path
bosch_camera_snapshot	LAN only — HTTP Digest to camera IP
bosch_camera_stream_url	LAN only — RTSPS via local Bosch TLS proxy
bosch_camera_lan_ping	LAN only — TCP connect to camera port 443
bosch_camera_list / status / events	Bosch cloud (no local API yet)
bosch_camera_privacy_set / light_set (default)	Bosch cloud
bosch_camera_privacy_set / light_set (prefer_local=True)	LAN-RCP first, cloud fallback — Gen2 only
bosch_camera_pan / notifications_set	Bosch cloud (no local API yet)

The MCP host must be on the same network as the cameras for media tools to work. If it isn't, the snapshot/stream tools surface local_unavailable rather than falling back to cloud — by design.

Auth model

Server runs with the user's existing bosch_config.json from the sister Python tool — no separate OAuth flow. Two startup modes:

1. --config-from-cli (default): expects bosch_config.json next to bosch_camera.py in a sibling checkout
2. --config <path>: explicit path to a bosch_config.json

The MCP server never reads or writes credentials beyond what the CLI tool already does (token refresh on 401, atomic save).

Transport modes

Three transport modes are supported via the --transport flag:

Mode	Flag	Use case
stdio	--transport stdio (default)	Claude Code / Claude Desktop — local subprocess
streamable-http	--transport http	Remote / multi-client deployments over HTTP
sse	--transport sse	Legacy SSE clients

HTTP and SSE modes bind to 127.0.0.1:8765 by default (security-safe local-only). Pass --http-host 0.0.0.0 only in trusted, firewalled network environments.

# stdio (default) — used by Claude Code / Claude Desktop
bosch-smart-home-camera-mcp --config ~/.config/bosch-camera/bosch_config.json

# streamable-HTTP — local port for multi-client use
bosch-smart-home-camera-mcp --transport http --http-port 8765

# streamable-HTTP — expose to LAN (ensure firewall rules!)
bosch-smart-home-camera-mcp --transport http --http-host 0.0.0.0 --http-port 8765

Tech stack

• Python 3.10+
• mcp — official Anthropic Python SDK
• pydantic (already a transitive dep of mcp) for tool schemas
• Reuse: bosch_camera.py from sister repo as a Git submodule or as a Python import path

Installation

# via pipx (recommended for end users — isolated environment, PATH entry)
pipx install bosch-smart-home-camera-mcp

# via uvx (zero-install, one-shot — no persistent env needed)
uvx bosch-smart-home-camera-mcp --help

# from source (for development)
pip install -e .[test]

Maintainers: PyPI publishing is automated — pushing a v*.*.* tag triggers the publish-pypi workflow via OIDC Trusted Publisher. Do not run twine upload manually.

Add to Claude Code — stdio (local, recommended)

claude mcp add bosch-camera -- bosch-smart-home-camera-mcp \
  --config ~/.config/bosch-camera/bosch_config.json

Add to Claude Code — streamable-HTTP (remote server)

# Start server first:
bosch-smart-home-camera-mcp --transport http --http-port 8765

# Then register the HTTP endpoint:
claude mcp add bosch-camera --transport http http://127.0.0.1:8765/mcp

Repo layout

Bosch-Smart-Home-Camera-Tool-MCP/
├── README.md                         this file
├── LICENSE                           MIT
├── pyproject.toml                    build + tool config
├── requirements.txt                  runtime pins (mcp, etc.)
├── requirements-test.txt             pytest, pytest-asyncio, mocks
├── src/
│   └── bosch_camera_mcp/
│       ├── __init__.py
│       ├── server.py                 FastMCP server + all 16 MCP tools
│       ├── adapters/
│       │   ├── cli_bridge.py         bridge to Python CLI for cloud ops
│       │   └── __init__.py
│       ├── lan_rcp.py                direct LAN HTTPS+Digest for RCP writes
│       ├── maintenance.py            cloud maintenance RSS feed fetcher
│       ├── errors.py                 shared error types
│       ├── resources.py              MCP resources (bosch://cameras/…)
│       └── prompts.py                MCP prompts (daily-summary, pre-leave)
├── tests/
│   ├── test_tools_integration.py
│   ├── test_audio_intrusion_wifi.py
│   ├── test_cert_pinning.py
│   ├── test_cred_rotation.py
│   ├── test_lan_ping.py
│   ├── test_lan_rcp_https.py
│   ├── test_maintenance.py
│   ├── test_packaging.py
│   ├── test_pan_presets.py
│   ├── test_prompts.py
│   ├── test_resources.py
│   ├── test_skeleton.py
│   └── test_transport.py
├── docs/
│   ├── architecture.md
│   └── release-process.md
└── .gitignore

Roadmap

• v0.1.0 — concept doc + skeleton server, all tools defined but not yet implemented (returns NotImplementedError) ✅
• v0.2.0 — all 8 tools wired: read tools (list, status, events, snapshot) + write tools (privacy, light, pan, notifications) via sys.path injection (Option C) ✅
• v0.4.0 — resources (bosch://cameras, bosch://cameras/{name}/snapshot.jpg, bosch://cameras/{name}/events) + prompts (daily-camera-summary, pre-leave-check) ✅
• v0.5.0 — streamable-HTTP transport (--transport http|sse|stdio), packaging for pipx/uvx, 24 new tests ✅
• v1.0.0 — first stable release: 106 tests, published wheel + sdist on GitHub Releases, PyPI publish pending ✅
• v1.1.0 — LAN-only media path (privacy hardened): bosch_camera_snapshot and new bosch_camera_stream_url go directly to camera over LAN, no Bosch cloud relay for media. 113 tests. ✅
• v1.2.0 — bosch_camera_maintenance_status tool: fetches cloud maintenance announcements from community RSS feeds; returns state (active/scheduled/past/recent/unknown/idle), title, time window, link. ✅
• v1.3.0 — LAN-fallback feature set (ported from HA integration v12.4.10/v12.4.11): bosch_camera_lan_ping tool (TCP-probe any camera on LAN); prefer_local=True on bosch_camera_privacy_set / bosch_camera_light_set (RCP-LAN write path, Gen2, cloud fallback on failure); recommended_action field on bosch_camera_maintenance_status ("check_lan" when active, "wait" when scheduled). 173 tests. ✅
• v1.3.3 — audio get/set, intrusion detection get/set, WiFi info (cross-port from HA v12.7.0). 16 tools. ✅
• v1.3.4 — PTZ named presets (bosch_camera_pan preset= accepts home / left / right / back-left / back-right; overrides angle); transparent cred-rotation on 401 for LAN-RCP tools (silent retry, no API change). ✅
• v1.3.6 — 9 bug fixes from live audit 2026-05-24 (camera list always live from cloud, Gen1/Gen2 hw_version, UUID resolution, events field mapping, audio camelCase, intrusion Gen2 gate, error codes, snapshot timestamp, requirements-test.txt mirror). ✅
• v1.3.5 — README fixes: version refs, repo layout, tool inventory. ✅
• v1.4.0 (next) — 4 new tools: bosch_camera_mjpeg_snapshot (direct RTSP frame via ffmpeg, Gen2 LAN), bosch_camera_onvif_scopes (RCP 0x0a98 LAN), bosch_camera_rcp_version (RCP 0xff00+0xff04 LAN), bosch_camera_feature_flags (account-level /v11/feature_flags). _fetch_rcp_lan async helper. 20 tools total.

License

MIT — see LICENSE.