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.8.0 — local data interface status + local stream URL; family-parity closeout (v1.7.0): motion zones, privacy masks, automation rules, camera sharing/friends, firmware install, siren duration, lighting schedule, listen-audio intercom. Plus the 2026-08-19 image/video tuning + camera-lifecycle round: timestamp overlay, status LED, lens elevation, darkness threshold, white balance, top/bottom LED brightness, soft/hard reset, rename. 71 tools + 3 resources + 2 prompts, stdio/SSE/streamable-HTTP, pipx/uvx-installable

Table of Contents

• Disclaimer
• Why a separate MCP server?
• Architecture
• MCP tools
• MCP resources
• MCP prompts
• Privacy stance
• Auth model
• Transport modes
• Tech stack
• Installation
• Repo layout
• Release History
• Releases · Full changelog · GitHub Releases
• Integration Comparison — pick the right project for your platform
• Related Projects
• License

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:

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.

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.

This is a real runtime dependency, not just a doc reference. The server locates bosch_camera.py at process startup via sys.path injection (adapters/cli_bridge.py) rather than a normal pip install dependency — the sister Python CLI tool repo must be checked out on disk, and the MCP server needs to know where. Resolution order: the BOSCH_CAMERA_CLI_PATH environment variable if set, otherwise a fixed default path used by the maintainer's own setup (not portable — override it). Nearly every tool call ends up importing bosch_camera from that path at call time (ensure_cli_importable()), so a missing or wrong path surfaces as an ImportError on the first tool invocation, not at server startup. Practically: clone both repos, then either set BOSCH_CAMERA_CLI_PATH=/path/to/Bosch-Smart-Home-Camera-Tool-Python in the environment the MCP server runs in, or edit DEFAULT_CLI_PATH in adapters/cli_bridge.py for a permanent local install. The same bosch_config.json the CLI tool produces via bosch_camera login is what this server reads for credentials — see Auth model.

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 (70 total, v1.7.2)

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

• Token refresh (handled silently by the underlying client)
• Cloud clip download (large payloads)
• Two-way talk (caller mic → camera speaker): not exposed by the Bosch cloud API at all (same limitation the sister CLI has) — bosch_camera_intercom_open is listen-only

Ported from the HA integration but deliberately NOT added (architecture mismatch — see docs/family-parity-plan.md 2026-08-19 audit for the full reasoning):

• open_live_connection (explicit session open/keep-alive) — MCP tools are one-shot request/response calls with no persistent background process to hold a session open between calls; bosch_camera_stream_url already mints a fresh, immediately-usable URL per call, which is the MCP-shaped equivalent.
• Frigate/external-RTSP "front door" (persistent credential-free RTSP server) — same reason: requires a long-running server process, which this stateless tool surface doesn't have.
• delete_event / send_event_webhook — both operate on HA's own local-disk event-file cache and webhook_url/enable_webhook_delivery config, infrastructure this tool doesn't have (events here are pulled on-demand from the Bosch cloud, never stored locally).
• AI alert history read-back — HA's ai_alert_store.py reads from hass.config.path-relative files in HA's own storage layout; coupling to that would be fragile and isn't clearly useful when the MCP client is itself typically the LLM doing the analysis.
• video_quality / stream_mode selects and image_rotation_180 — all three are client-side-only preferences in HA (no Bosch cloud API call at all: quality picks the RTSPS inst= parameter, stream_mode picks LOCAL vs REMOTE, rotation is a display-only CSS/PIL transform) with no persistent per-session state to attach them to here. pan_preset is already covered — bosch_camera_pan(preset=...) has shipped since v1.x.

Reliability — transparent credential rotation

The prefer_local=True LAN-RCP write path (bosch_camera_privacy_set, bosch_camera_light_set) automatically retries 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. bosch_camera_pan does not currently take a prefer_local parameter — pan always goes through the Bosch cloud.

MCP resources

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

MCP prompts

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.

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 CLI tool — no separate OAuth flow, no credentials stored by this repo. Generate it once via the CLI's bosch_camera login (browser-based OAuth2 PKCE), then point the MCP server at it:

• --config <path> / BOSCH_CAMERA_CONFIG=<path> environment variable: explicit path to bosch_config.json.
• If neither is set, the bridge falls back to whatever get_session_and_cameras()'s default resolution finds next to the sister CLI checkout (see Architecture — the sister CLI's location is itself resolved via BOSCH_CAMERA_CLI_PATH or a fixed default path).

The MCP server never reads or writes credentials beyond what the CLI tool already does (token refresh on 401, atomic save) — it calls straight into the CLI's own session/config code via the cli_bridge import.

Transport modes

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

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 MCP Python SDK
• pydantic (already a transitive dep of mcp) for tool schemas
• Reuse: bosch_camera.py from the sister CLI repo, located at runtime via sys.path injection (BOSCH_CAMERA_CLI_PATH env var or a configurable default) — not a pip-installed dependency, see Architecture

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

Add to Claude Desktop

Add the following to your claude_desktop_config.json (usually ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "bosch-camera": {
      "command": "bosch-smart-home-camera-mcp",
      "args": [
        "--config",
        "/path/to/bosch_config.json"
      ]
    }
  }
}

Replace /path/to/bosch_config.json with the actual path to your bosch_config.json (generated by the sister Python CLI tool via bosch_camera login). The server runs as a local stdio subprocess — no network port needed for Claude Desktop.

Repo layout

Bosch-Smart-Home-Camera-Tool-MCP/
├── README.md                         this file
├── CHANGELOG.md                      full version history
├── 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 70 MCP tools
│       ├── adapters/
│       │   ├── cli_bridge.py         sys.path bridge to the sister Python CLI for cloud ops
│       │   └── __init__.py
│       ├── lan_rcp.py                direct LAN HTTPS+Digest for RCP writes
│       ├── cloud_ssl.py              pinned Bosch cloud CA / SSL context (CWE-295)
│       ├── time_utils.py             Bosch timestamp cleanup helpers
│       ├── maintenance.py            cloud maintenance RSS feed fetcher
│       ├── errors.py                 shared error types (MCPError)
│       ├── resources.py              MCP resources (bosch://cameras/…)
│       └── prompts.py                MCP prompts (daily-summary, pre-leave)
├── tests/                            30+ test modules — tool behavior, LAN-RCP/cred-rotation,
│                                      cert pinning, transports, resources, prompts, packaging
├── docs/
│   ├── architecture.md
│   └── release-process.md
└── .gitignore

Release History

• 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); 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.4.0 — 4 new tools: bosch_camera_mjpeg_snapshot, bosch_camera_onvif_scopes, bosch_camera_rcp_version, bosch_camera_feature_flags. _fetch_rcp_lan async helper. 20 tools total. ✅
• v1.5.0 — 11 new tools + 8 bug fixes from live-camera audit (4 hardware units, all 4 generations): siren trigger, motion get/set, recording get/set, autofollow get/set, privacy-sound get/set, unread-count, health-check-all, token-status. ✅
• v1.5.1 — fixed _fetch_rcp_lan (used a non-existent aiohttp.DigestAuth → onvif_scopes / rcp_version always failed over LAN; now httpx.DigestAuth). Test coverage 83→98%, fixtures sanitized, CI bumped to Node-24-native action majors. ✅
• v1.5.2 — dependency hygiene: dropped unused aiohttp runtime dep (test-only now), added pyjwt>=2.13.0 / starlette>=1.0.1 security floors (pip-audit clean), fixed a test that mocked the wrong HTTP stack. ✅
• v1.5.3 — security patch: pin Bosch cloud CA for the MCP cloud session (CWE-295, GHSA-6qh5-x5m5-vj6v); closes adjacent-network MITM on OAuth tokens. Local TOFU pinning unchanged. ✅
• v1.5.4 — event timestamps no longer drop the timezone offset: /v11/events returns offset-bearing timestamps (e.g. +02:00[Europe/Berlin]); the server now strips only the trailing [zone] suffix instead of truncating to 19 characters, preserving the explicit UTC offset. ✅
• v1.5.5 — camera_events resource now uses eventType + eventTags for correct event classification. ✅
• v1.6.0 — 2 new tools: bosch_camera_audio_detection_get / bosch_camera_audio_detection_set — glass-break + smoke/fire-alarm sound detection for Gen2 Audio-Plus cameras (cross-port from HA integration v14.2.0). 34 tools total. ✅
• v1.7.0 — family-parity closeout (docs/family-parity-plan.md §2b): 21 new tools closing the MCP-vs-HA/CLI capability gap — motion zones get/set/clear, privacy masks get/set/clear, automation rules list/add/edit/delete, camera sharing/friends list/invite/share/unshare/remove, firmware status/install (mirrors HA's async_install_firmware guard), siren duration, LED lighting schedule get/set, and a listen-audio intercom tool (camera mic → caller, RTSPS URL; two-way talk is not exposed by Bosch's cloud API at all, same limitation as the sister CLI). CI hardening: coverage gate (--cov-fail-under=96), pip-audit (runtime deps only), pylint, codespell, CodeQL, gitleaks secret-scan, and a dependency-review workflow — Gold-tier parity with the HA integration's quality gates. 55 tools total. ✅
• v1.7.2 — docs-only: fixed this repo's Login row in the Integration Comparison table, no functional changes. ✅

Releases

Latest: v1.7.2 — see the GitHub release page for full notes: v1.7.2 release notes →

Integration Comparison

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

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.

Related Projects

Part of a five-implementation family for Bosch Smart Home Cameras (plus an alpha frontend):

Also: Bosch Smart Home Camera — Python Frontend (NiceGUI) — v0.4.2-alpha (dashboard + camera detail + settings) — community interest welcome

HA stays the reference implementation — features land there first; the Python CLI, ioBroker Adapter and MCP Server catch up over time.

License

MIT — see LICENSE.