{"id":49418332,"url":"https://github.com/groupthink-dev/google-home-blade-mcp","last_synced_at":"2026-04-29T04:12:20.082Z","repository":{"id":354331613,"uuid":"1200356771","full_name":"Groupthink-dev/google-home-blade-mcp","owner":"Groupthink-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T04:32:19.000Z","size":125,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T06:28:23.140Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Groupthink-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-03T10:12:09.000Z","updated_at":"2026-04-28T04:32:19.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Groupthink-dev/google-home-blade-mcp","commit_stats":null,"previous_names":["groupthink-dev/google-home-blade-mcp"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/Groupthink-dev/google-home-blade-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fgoogle-home-blade-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fgoogle-home-blade-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fgoogle-home-blade-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fgoogle-home-blade-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Groupthink-dev","download_url":"https://codeload.github.com/Groupthink-dev/google-home-blade-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fgoogle-home-blade-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32407176,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-28T19:38:08.556Z","status":"online","status_checked_at":"2026-04-29T02:00:06.602Z","response_time":110,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T04:12:16.321Z","updated_at":"2026-04-29T04:12:20.076Z","avatar_url":"https://github.com/Groupthink-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# google-home-blade-mcp\n\n**Security-first, token-efficient MCP server for Google Home and Nest devices via the Smart Device Management API.**\n\nControl thermostats, stream cameras, monitor doorbells, and pull device events — all through a hardened MCP interface designed for LLM-driven home automation.\n\n## Why This Exists\n\n| | ghome-mcp-server | Google's Cloud MCPs | **google-home-blade-mcp** |\n|---|---|---|---|\n| **Device coverage** | Smart plugs only | No Google Home MCP | Full SDM: thermostats, cameras, doorbells, displays |\n| **Security model** | None | IAM-only | Write gates + confirm gates + credential scrubbing |\n| **Token efficiency** | Verbose JSON | N/A | Pipe-delimited, null-omission, ~25 tokens/device |\n| **Thermostat control** | No | No | Mode, setpoint, eco, fan — all with safety gates |\n| **Camera streams** | No | No | WebRTC/RTSP with 5-min session management |\n| **Event streaming** | No | No | Pub/Sub integration for motion, person, doorbell events |\n| **Batch operations** | No | N/A | `ghome_status` dashboard, `ghome_thermostats` overview |\n| **Marketplace ready** | No | No | `sidereal-plugin.yaml`, `home-v1` contract, SKILL.md |\n\n### Design Principles\n\n1. **Security-first** — Every device command requires explicit write enablement. Destructive operations require double confirmation. OAuth tokens never appear in output. Access tokens live in memory only.\n2. **Token efficiency** — Compact pipe-delimited output. Null fields omitted. Dashboard views compress entire device fleets into minimal tokens. One `ghome_status` call replaces N individual queries.\n3. **Event-driven** — Pub/Sub integration enables webhook-style triggers for motion detection, doorbell presses, and state changes. No polling required.\n\n## Quick Start\n\n```bash\n# Install\ngit clone https://github.com/groupthink-dev/google-home-blade-mcp.git\ncd google-home-blade-mcp\nmake install-dev\n\n# Set up OAuth (one-time interactive flow)\nexport GOOGLE_HOME_CLIENT_ID=\"your-client-id\"\nexport GOOGLE_HOME_CLIENT_SECRET=\"your-client-secret\"\nexport GOOGLE_HOME_PROJECT_ID=\"your-sdm-project-id\"\nmake auth\n# → Opens browser → Google consent → prints refresh token\n\n# Configure\nexport GOOGLE_HOME_REFRESH_TOKEN=\"the-refresh-token-from-above\"\nexport GOOGLE_HOME_WRITE_ENABLED=true   # optional: enable device commands\n\n# Run\nmake run\n```\n\n### Prerequisites\n\n1. **Google Cloud project** with [Smart Device Management API](https://console.cloud.google.com/apis/library/smartdevicemanagement.googleapis.com) enabled\n2. **Device Access Console** registration at [console.nest.google.com/device-access](https://console.nest.google.com/device-access) ($5 USD one-time fee)\n3. **OAuth 2.0 credentials** (Web application type) in GCP Console\n4. At least one Nest device linked to your Google account\n\n## Tools (15)\n\n### Read (8 tools)\n\n| Tool | Purpose | Tokens |\n|------|---------|--------|\n| `ghome_info` | Health check: API status, device counts, write gate | ~30 |\n| `ghome_structures` | List homes | ~15/structure |\n| `ghome_rooms` | List rooms in a structure | ~10/room |\n| `ghome_devices` | List all devices (filterable by type) | ~25/device |\n| `ghome_device` | Full device detail with all traits | ~80-120 |\n| `ghome_status` | Compact dashboard — all devices, one line each | ~25/device |\n| `ghome_thermostats` | All thermostats at a glance | ~30/thermostat |\n| `ghome_events` | Pull recent events from Pub/Sub | ~20/event |\n\n### Write (7 tools, gated)\n\n| Tool | Purpose | Gate |\n|------|---------|------|\n| `ghome_thermostat_mode` | Set mode: HEAT, COOL, HEATCOOL, OFF | write |\n| `ghome_thermostat_setpoint` | Set target temperature (heat, cool, or range) | write |\n| `ghome_thermostat_eco` | Toggle eco mode | write |\n| `ghome_fan_set` | Fan timer control | write |\n| `ghome_camera_stream` | Generate live stream URL (WebRTC/RTSP) | write |\n| `ghome_camera_image` | Get snapshot from camera event | write |\n| `ghome_command` | Execute any SDM command (escape hatch) | write + confirm |\n\n## Output Format\n\nToken-efficient pipe-delimited output with null-field omission:\n\n```\n# ghome_status\n## Devices: 4 total, 4 online\nLiving Room | Thermostat | room=Living Room | online | 21.5°C | mode=HEAT | hvac=HEATING | id=abc123\nMaster Bedroom | Thermostat | room=Bedroom | online | 19.8°C | mode=ECO | hvac=OFF | id=def456\nFront Door | Doorbell | room=Entry | online | events=motion,person,chime | id=ghi789\nGarden | Camera | room=Outdoor | online | events=motion,person | id=jkl012\n\n# ghome_thermostats\nLiving Room | Living Room | ambient=21.5°C | humidity=45% | mode=HEAT | heat→22.0°C | hvac=HEATING | online | id=abc123\nMaster Bedroom | Bedroom | ambient=19.8°C | humidity=52% | mode=HEAT | eco=MANUAL_ECO | hvac=OFF | online | id=def456\n```\n\n## Security Model\n\n### Three-layer protection\n\n1. **Write gate** — All device commands blocked unless `GOOGLE_HOME_WRITE_ENABLED=true`. Read operations always allowed.\n2. **Confirm gate** — `ghome_command` (raw SDM command execution) requires `confirm=true` as an additional parameter.\n3. **Credential scrubbing** — OAuth access tokens (`ya29.*`), refresh tokens (`1//*`), Bearer headers, and client secrets are stripped from all error messages before output.\n\n### Token lifecycle\n\n- **Refresh token** stored in env var (never in code, never on disk beyond env)\n- **Access tokens** refreshed automatically, kept in memory only, 60-second pre-expiry buffer\n- **401 responses** trigger automatic token invalidation and re-auth on next request\n- **Bearer auth** available for HTTP transport (optional `GOOGLE_HOME_MCP_API_TOKEN`)\n\n## Claude Code Integration\n\nAdd to your `settings.json` or `claude.nix`:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-home\": {\n      \"command\": \"uv\",\n      \"args\": [\"--directory\", \"/path/to/google-home-blade-mcp\", \"run\", \"google-home-blade-mcp\"],\n      \"env\": {\n        \"GOOGLE_HOME_CLIENT_ID\": \"your-client-id\",\n        \"GOOGLE_HOME_CLIENT_SECRET\": \"your-secret\",\n        \"GOOGLE_HOME_REFRESH_TOKEN\": \"your-refresh-token\",\n        \"GOOGLE_HOME_PROJECT_ID\": \"your-project-id\",\n        \"GOOGLE_HOME_WRITE_ENABLED\": \"false\"\n      }\n    }\n  }\n}\n```\n\n## Pub/Sub Event Streaming\n\nFor event-driven automation (motion alerts, doorbell presses, temperature changes):\n\n1. Create a Pub/Sub topic in GCP Console linked to your Device Access project\n2. Create a subscription for the topic\n3. Set `GOOGLE_HOME_PUBSUB_SUBSCRIPTION=projects/{project}/subscriptions/{name}`\n4. Use `ghome_events` to pull and acknowledge events\n\nEvents include device trait updates, camera motion/person detection, and doorbell chime events — enabling webhook-style triggers without polling.\n\n## Supported Devices\n\n| Device | Read | Control | Stream | Events |\n|--------|------|---------|--------|--------|\n| Nest Thermostat | ambient, humidity, mode, setpoint, HVAC, eco | mode, setpoint, eco, fan | — | trait updates |\n| Nest Camera | status, capabilities | — | WebRTC, RTSP | motion, person, sound |\n| Nest Doorbell | status, capabilities | — | WebRTC | motion, person, chime |\n| Nest Hub Max | status | — | — | — |\n\n## Development\n\n```bash\nmake install-dev    # Install with dev + test dependencies\nmake test           # Run unit tests\nmake test-cov       # Run with coverage report\nmake lint           # Ruff linter\nmake format         # Ruff formatter\nmake type-check     # MyPy strict mode\nmake check          # All quality checks\n```\n\n### Architecture\n\n```\nsrc/google_home_blade_mcp/\n├── server.py       # 15 FastMCP tools (read + write-gated)\n├── client.py       # SDM API client (httpx, error classification)\n├── auth.py         # OAuth2 token manager (memory-only access tokens)\n├── traits.py       # Trait parsing + command builders\n├── formatters.py   # Token-efficient output (pipe-delimited, null-omission)\n├── models.py       # Config, device types, exceptions, credential scrubbing\n└── auth_setup.py   # Interactive OAuth2 setup (make auth)\n```\n\n### Rate Limits\n\n| Operation | Limit |\n|-----------|-------|\n| Device commands | 5/min per device |\n| API aggregate | 6,000 req/60s per project |\n| Camera streams | 5-min sessions (extendable) |\n| Sandbox users | 25 max across 5 structures |\n\n## Sidereal Marketplace\n\nThis blade ships with full marketplace scaffolding:\n\n- `sidereal-plugin.yaml` — Plugin manifest with `home-v1` contract, OAuth2 setup block, conformance declaration\n- `SKILL.md` — Token efficiency rules, workflow examples, tool reference for Claude\n- Security model aligned with Sidereal trust tiers (write gates, confirm gates, credential scrubbing)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fgoogle-home-blade-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupthink-dev%2Fgoogle-home-blade-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fgoogle-home-blade-mcp/lists"}