展示 HN：SharkClean MCP

展示 HN：SharkClean MCP
Show HN: SharkClean MCP

原始链接: https://github.com/a-funk/sharkclean-mcp

这是一个非官方的 MCP 服务器，旨在让 AI 智能体（如 Claude Desktop 或 Claude Code）能够控制现代 SharkNinja 扫地机器人。与依赖旧版 Ayla 云端（常导致 Matrix、AI Ultra 等新款机型显示“离线”）的旧集成不同，此工具可直接与 SharkNinja 现有的“skegox”后端通信。 **主要功能：** * **智能体控制：** 通过自然语言启动全屋或特定房间的清扫、调节吸力模式、暂停/恢复以及返回基站。 * **实时状态：** 查看电量、当前工作状态及错误信息。 * **多设备支持：** 通过设备 ID 或名称管理多台设备。 * **脚本支持：** 包含用于命令行控制的 `shark-mcp-rc`，非常适合 cron 任务或自动化脚本。 **设置：** 需要 Python 3.10+ 和 `uv`。克隆项目后，需进行一次基于 PKCE 的浏览器认证，以处理 SharkNinja 的安全登录流程。凭据将被安全缓存，服务器会自动刷新令牌。 **集成：** 使用 `uv run` 将该服务器添加到您的 MCP 客户端配置中。由于本项目使用了逆向工程 API，因此与 SharkNinja 无官方关联，功能稳定性取决于其云端后端的表现。如需详细用法、测试及安全文档，请访问 [GitHub 仓库](https://github.com/a-funk/sharkclean-mcp)。

```Hacker News最新 | 过往 | 评论 | 提问 | 展示 | 招聘 | 提交登录Show HN: SharkClean MCP (github.com/a-funk)4 分，由 afunk 在 1 小时前发布 | 隐藏 | 过往 | 收藏 | 讨论这没什么特别的，但通过 MCP 远程启动清洁任务确实非常非常好用。正朝着真正的智能家居努力，这是朝着正确方向迈出的有益一步。帮助指南 | 常见问题解答 | 列表 | API | 安全 | 法律 | 申请 YC | 联系搜索： ```

原文

An MCP server for SharkClean / SharkNinja robot vacuums. Lets any MCP client (Claude Code, Claude Desktop, etc.) start cleanings, clean specific rooms, send the robot home, and check status — agentically, in plain language.

Unofficial — not affiliated with or endorsed by SharkNinja.

All 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.

Why not the Ayla cloud? The widely-used sharkiq SDK (and the Home Assistant Shark IQ integration built on it) talk to SharkNinja's legacy Ayla 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 can't reach. The reverse engineering of the skegox API is owed to the shark2mqtt project.

Tool	What it does
`list_robots`	List robots on the account (name, device id)
`get_status`	Live state: cleaning/paused/docked, battery %, charging, power mode, online, errors
`start_cleaning`	Whole-home clean, optional power mode (`eco`/`normal`/`max`)
`list_rooms`	Rooms the robot knows from its current map (with floor id + last-updated)
`clean_rooms`	Clean only specific rooms (validated against the live map)
`pause_cleaning` / `resume_cleaning` / `stop_cleaning`	Run control
`return_to_dock`	Send the robot home to recharge / self-empty
`set_power_mode`	Suction: `eco`, `normal`, `max`
`locate_robot`	Make the robot beep

start_cleaning and clean_rooms first check the robot is online and refuse if it isn't, so commands don't silently vanish. Multi-robot accounts are supported — every tool takes an optional robot argument (name or device id). With one robot, omit it.

Requires uv and Python ≥ 3.10.

git clone https://github.com/a-funk/sharkclean-mcp
cd sharkclean-mcp
uv sync
cp .env.example .env       # add your SharkClean app email + password
uv run shark-mcp-auth      # one-time browser login (see below)
uv run shark-mcp-doctor    # confirm: prints your robot + current room map

One-time login (`shark-mcp-auth`)

SharkNinja's Auth0 tenant blocks headless password logins, so the first login happens in your browser using the SharkClean app's own PKCE flow:

shark-mcp-auth opens the real SharkClean login page.
Log in. The browser then tries to redirect to com.sharkninja.shark://... and usually shows an error, blank page, or an "Open SharkClean?" dialog — that's expected.
Copy that full com.sharkninja.shark://... URL (from the address bar, browser history, or the DevTools Network tab with "Preserve log" on) and paste it at the prompt.

That's it. Tokens are cached at ~/.config/shark-mcp/tokens.json (mode 600) and refreshed automatically; you won't need the browser again. See SECURITY.md for how credentials are handled.

Register with your MCP client

Claude Code (user-wide):

claude mcp add --scope user sharkclean -- uv run --directory /ABSOLUTE/PATH/TO/sharkclean-mcp shark-mcp

Or copy .mcp.json.example to .mcp.json, set the absolute path, and Claude Code will pick it up automatically when opened in this directory.

Claude Desktop — add to claude_desktop_config.json:

{
  "mcpServers": {
    "sharkclean": {
      "command": "uv",
      "args": ["run", "--directory", "/ABSOLUTE/PATH/TO/sharkclean-mcp", "shark-mcp"]
    }
  }
}

Credentials come from environment variables or the .env file: SHARKCLEAN_EMAIL, SHARKCLEAN_PASSWORD, and optionally SHARKCLEAN_REGION=eu.

"Start a max-power clean."
"Vacuum the kitchen and the living room."
"Is the shark done? What's its battery at?"
"Send the robot back to its dock."

Beyond the MCP server, shark-mcp-rc drives the robot from a shell (handy for scripts/cron):

uv run shark-mcp-rc status
uv run shark-mcp-rc rooms
uv run shark-mcp-rc clean Kitchen "Living Room"
uv run shark-mcp-rc start max
uv run shark-mcp-rc dock

uv run pytest            # unit tests (fake robot, no cloud calls)
uv run shark-mcp         # run the server on stdio
uv run shark-mcp-doctor  # live end-to-end check against the cloud

See CONTRIBUTING.md. If your robot works, add it to CONFIRMED_MODELS.md.

Auth: the one-time browser login (shark-mcp-auth) yields an Auth0 refresh token, cached at ~/.config/shark-mcp/tokens.json. 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, re-run shark-mcp-auth.
Headless/scripted password login is blocked by Auth0 bot detection ("Suspicious request requires verification"); the browser flow is the reliable path.
Room targeting (clean_rooms) 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.