{"slug": "show-hn-sharkclean-mcp", "title": "Show HN: SharkClean MCP", "summary": "A developer released SharkClean MCP, an unofficial open-source server that lets AI agents like Claude control SharkNinja robot vacuums via plain language commands. The tool communicates with SharkNinja's skegox cloud backend, enabling support for newer robots that the legacy sharkiq SDK cannot reach.", "body_md": "An [MCP](https://modelcontextprotocol.io) server for [SharkClean](https://www.sharkclean.com/) /\nSharkNinja robot vacuums. Lets any MCP client (Claude Code, Claude Desktop, etc.) start\ncleanings, clean specific rooms, send the robot home, and check status — agentically, in\nplain language.\n\nUnofficial — not affiliated with or endorsed by SharkNinja.\n\nAll commands go through SharkNinja's current cloud (\"skegox\") — the same backend the SharkClean app uses — so the robot behaves exactly as if driven from the app, with no hardware modification.\n\nWhy not the Ayla cloud?The widely-used`sharkiq`\n\nSDK (and the Home Assistant Shark IQ integration built on it) talk to SharkNinja'slegacyAyla IoT cloud. Newer robots (Matrix, AI Ultra, Mach 2, the RV2500+ generation) have been migrated off Ayla onto the skegox backend. On Ayla those robots show up permanently \"Offline\" with a frozen, stale room map, even though the app controls them fine. This server talks to skegox directly, which is why it works with the newer robots that`sharkiq`\n\ncan't reach. The reverse engineering of the skegox API is owed to the[shark2mqtt]project.\n\n| Tool | What it does |\n|---|---|\n`list_robots` |\nList robots on the account (name, device id) |\n`get_status` |\nLive state: cleaning/paused/docked, battery %, charging, power mode, online, errors |\n`start_cleaning` |\nWhole-home clean, optional power mode (`eco` /`normal` /`max` ) |\n`list_rooms` |\nRooms the robot knows from its current map (with floor id + last-updated) |\n`clean_rooms` |\nClean only specific rooms (validated against the live map) |\n`pause_cleaning` / `resume_cleaning` / `stop_cleaning` |\nRun control |\n`return_to_dock` |\nSend the robot home to recharge / self-empty |\n`set_power_mode` |\nSuction: `eco` , `normal` , `max` |\n`locate_robot` |\nMake the robot beep |\n\n`start_cleaning`\n\nand `clean_rooms`\n\nfirst check the robot is online and refuse if it isn't,\nso commands don't silently vanish. Multi-robot accounts are supported — every tool takes an\noptional `robot`\n\nargument (name or device id). With one robot, omit it.\n\nRequires [uv](https://docs.astral.sh/uv/) and Python ≥ 3.10.\n\n```\ngit clone https://github.com/a-funk/sharkclean-mcp\ncd sharkclean-mcp\nuv sync\ncp .env.example .env       # add your SharkClean app email + password\nuv run shark-mcp-auth      # one-time browser login (see below)\nuv run shark-mcp-doctor    # confirm: prints your robot + current room map\n```\n\nSharkNinja's Auth0 tenant blocks headless password logins, so the first login happens in your browser using the SharkClean app's own PKCE flow:\n\n`shark-mcp-auth`\n\nopens the real SharkClean login page.- Log in. The browser then tries to redirect to\n`com.sharkninja.shark://...`\n\nand usually shows an error, blank page, or an \"Open SharkClean?\" dialog — that's expected. - Copy that full\n`com.sharkninja.shark://...`\n\nURL (from the address bar, browser history, or the DevTools Network tab with \"Preserve log\" on) and paste it at the prompt.\n\nThat's it. Tokens are cached at `~/.config/shark-mcp/tokens.json`\n\n(mode `600`\n\n) and refreshed\nautomatically; you won't need the browser again. See [SECURITY.md](/a-funk/sharkclean-mcp/blob/main/SECURITY.md) for how\ncredentials are handled.\n\n**Claude Code** (user-wide):\n\n```\nclaude mcp add --scope user sharkclean -- uv run --directory /ABSOLUTE/PATH/TO/sharkclean-mcp shark-mcp\n```\n\nOr copy `.mcp.json.example`\n\nto `.mcp.json`\n\n, set the absolute path, and Claude Code will pick\nit up automatically when opened in this directory.\n\n**Claude Desktop** — add to `claude_desktop_config.json`\n\n:\n\n```\n{\n  \"mcpServers\": {\n    \"sharkclean\": {\n      \"command\": \"uv\",\n      \"args\": [\"run\", \"--directory\", \"/ABSOLUTE/PATH/TO/sharkclean-mcp\", \"shark-mcp\"]\n    }\n  }\n}\n```\n\nCredentials come from environment variables or the `.env`\n\nfile: `SHARKCLEAN_EMAIL`\n\n,\n`SHARKCLEAN_PASSWORD`\n\n, and optionally `SHARKCLEAN_REGION=eu`\n\n.\n\n- \"Start a max-power clean.\"\n- \"Vacuum the kitchen and the living room.\"\n- \"Is the shark done? What's its battery at?\"\n- \"Send the robot back to its dock.\"\n\nBeyond the MCP server, `shark-mcp-rc`\n\ndrives the robot from a shell (handy for scripts/cron):\n\n```\nuv run shark-mcp-rc status\nuv run shark-mcp-rc rooms\nuv run shark-mcp-rc clean Kitchen \"Living Room\"\nuv run shark-mcp-rc start max\nuv run shark-mcp-rc dock\nuv run pytest            # unit tests (fake robot, no cloud calls)\nuv run shark-mcp         # run the server on stdio\nuv run shark-mcp-doctor  # live end-to-end check against the cloud\n```\n\nSee [CONTRIBUTING.md](/a-funk/sharkclean-mcp/blob/main/CONTRIBUTING.md). If your robot works, add it to\n[CONFIRMED_MODELS.md](/a-funk/sharkclean-mcp/blob/main/CONFIRMED_MODELS.md).\n\n- Auth: the one-time browser login (\n`shark-mcp-auth`\n\n) yields an Auth0 refresh token, cached at`~/.config/shark-mcp/tokens.json`\n\n. The server mints short-lived skegox id_tokens from it. SharkNinja's Auth0 tenant rotates refresh tokens, so the server persists the rotated token on every refresh — if you see`invalid_grant`\n\n, re-run`shark-mcp-auth`\n\n. - Headless/scripted password login is blocked by Auth0 bot detection (\"Suspicious request requires verification\"); the browser flow is the reliable path.\n- Room targeting (\n`clean_rooms`\n\n) requires a robot with a completed map; older models without room support report no rooms. - This is unofficial, built on community reverse engineering. SharkNinja can change the backend at any time.", "url": "https://wpnews.pro/news/show-hn-sharkclean-mcp", "canonical_source": "https://github.com/a-funk/sharkclean-mcp", "published_at": "2026-06-12 16:09:14+00:00", "updated_at": "2026-06-16 09:17:02.741826+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "robotics"], "entities": ["SharkNinja", "SharkClean", "Claude", "Ayla", "sharkiq", "shark2mqtt", "Auth0", "GitHub"], "alternates": {"html": "https://wpnews.pro/news/show-hn-sharkclean-mcp", "markdown": "https://wpnews.pro/news/show-hn-sharkclean-mcp.md", "text": "https://wpnews.pro/news/show-hn-sharkclean-mcp.txt", "jsonld": "https://wpnews.pro/news/show-hn-sharkclean-mcp.jsonld"}}