当前位置：首页 > news >正文

GitHub平台功能大揭秘：含AI创作与安全防护，适配SharkClean扫地机器人MCP服务器

news 2026/6/16 22:32:03

导航菜单

可切换导航。
[ ](/)
[ 登录 ](/login?return_to=https%3A%2F%2Fgithub.com%2Fa-funk%2Fsharkclean-mcp)
外观设置

平台

-AI 代码创作
- GitHub Copilot：借助 AI 编写更优质代码
- GitHub Copilot 应用：从问题到合并的直接代理
- MCP 注册表：新功能，集成外部工具
-开发者工作流
- Actions：自动化任何工作流
- Codespaces：即时开发环境
- Issues：规划和跟踪工作
- 代码审查：管理代码变更
-应用程序安全
- GitHub 高级安全：发现并修复漏洞
- 代码安全：在构建过程中保障代码安全
- 密钥保护：防患于未然，阻止信息泄露
-探索
- 为何选择 GitHub
- 文档
- 博客
- 更新日志
- 市场

查看所有功能

解决方案

-按公司规模划分
- 企业版
- 中小型团队版
- 初创公司版
- 非营利组织版
-按用例划分
- 应用现代化
- DevSecOps
- DevOps
- CI/CD
- 查看所有用例
-按行业划分
- 医疗保健
- 金融服务
- 制造业
- 政府部门
- 查看所有行业

查看所有解决方案

资源

-按主题探索
- AI
- 软件开发
- DevOps
- 安全
- 查看所有主题
-按类型探索
- 客户案例
- 活动与网络研讨会
- 电子书与报告
- 商业洞察
- GitHub 技能
-支持与服务
- 文档
- 客户支持
- 社区论坛
- 信任中心
- 合作伙伴

查看所有资源

开源

-社区
- GitHub 赞助：资助开源开发者
-项目
- 安全实验室
- 维护者社区
- 加速器
- GitHub 明星项目
- 存档项目
-仓库
- 主题
- 热门趋势
- 集合

企业版

-企业解决方案
- 企业平台：由 AI 驱动的开发者平台
-可用附加组件
- GitHub 高级安全：企业级安全功能
- Copilot for Business：企业级 AI 功能
- 高级支持：企业级 24/7 支持

定价

搜索或跳转至...

可进行搜索。
清除
搜索语法提示

提供反馈

我们会阅读每一条反馈，并认真对待您的意见。
包含我的电子邮件地址，以便能与我联系
取消提交反馈

保存的搜索

使用保存的搜索可以更快地过滤结果

名称	查询

要查看所有可用的限定符，请参阅我们的文档。
取消创建保存的搜索
[ 登录 ](/login?return_to=https%3A%2F%2Fgithub.com%2Fa-funk%2Fsharkclean-mcp)
[ 注册 ](/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E&source=header-repo&source_repo=a-funk%2Fsharkclean-mcp)
外观设置
重置焦点
您已在另一个标签页或窗口中登录。[重新加载]()以刷新您的会话。
您已在另一个标签页或窗口中注销。[重新加载]()以刷新您的会话。
您已在另一个标签页或窗口中切换账户。[重新加载]()以刷新您的会话。关闭提醒
{{ message }}
[ a-funk ](/a-funk) /[sharkclean-mcp](/a-funk/sharkclean-mcp)公开
- [ 通知 ](/login?return_to=%2Fa-funk%2Fsharkclean-mcp) 您必须登录才能更改通知设置
- [ 复刻 0 ](/login?return_to=%2Fa-funk%2Fsharkclean-mcp)
- [ 收藏 3 ](/login?return_to=%2Fa-funk%2Fsharkclean-mcp)
- [ 代码 ](/a-funk/sharkclean-mcp)
- [ 问题 0 ](/a-funk/sharkclean-mcp/issues)
- [ 拉取请求 1 ](/a-funk/sharkclean-mcp/pulls)
- [ 操作 ](/a-funk/sharkclean-mcp/actions)
- [ 项目 ](/a-funk/sharkclean-mcp/projects)
- [ 安全与质量 0 ](/a-funk/sharkclean-mcp/security)
- [ 洞察 ](/a-funk/sharkclean-mcp/pulse)

其他导航选项

- [ 代码 ](/a-funk/sharkclean-mcp)
- [ 问题 ](/a-funk/sharkclean-mcp/issues)
- [ 拉取请求 ](/a-funk/sharkclean-mcp/pulls)
- [ 操作 ](/a-funk/sharkclean-mcp/actions)
- [ 项目 ](/a-funk/sharkclean-mcp/projects)
- [ 安全与质量 ](/a-funk/sharkclean-mcp/security)
- [ 洞察 ](/a-funk/sharkclean-mcp/pulse)
[](/a-funk/sharkclean-mcp)

a-funk/sharkclean-mcp

主分支
[分支](/a-funk/sharkclean-mcp/branches)[标签](/a-funk/sharkclean-mcp/tags)
[](/a-funk/sharkclean-mcp/branches)[](/a-funk/sharkclean-mcp/tags)
转到文件
代码
打开更多操作菜单

文件夹和文件

名称	名称	最后提交消息	最后提交日期

历史记录

[6 次提交](/a-funk/sharkclean-mcp/commits/main/)
[](/a-funk/sharkclean-mcp/commits/main/)6 次提交
[.github/workflows](/a-funk/sharkclean-mcp/tree/main/.github/workflows "此路径跳过空目录")
| [.github/workflows](/a-funk/sharkclean-mcp/tree/main/.github/workflows "此路径跳过空目录")
| |
[src/shark_mcp](/a-funk/sharkclean-mcp/tree/main/src/shark_mcp "此路径跳过空目录")
| [src/shark_mcp](/a-funk/sharkclean-mcp/tree/main/src/shark_mcp "此路径跳过空目录")
| |
[tests](/a-funk/sharkclean-mcp/tree/main/tests "测试")
| [tests](/a-funk/sharkclean-mcp/tree/main/tests "测试")
| |
[.env.example](/a-funk/sharkclean-mcp/blob/main/.env.example ".env.example")
| [.env.example](/a-funk/sharkclean-mcp/blob/main/.env.example ".env.example")
| |
[.gitignore](/a-funk/sharkclean-mcp/blob/main/.gitignore ".gitignore")
| [.gitignore](/a-funk/sharkclean-mcp/blob/main/.gitignore ".gitignore")
| |
[.mcp.json.example](/a-funk/sharkclean-mcp/blob/main/.mcp.json.example ".mcp.json.example")
| [.mcp.json.example](/a-funk/sharkclean-mcp/blob/main/.mcp.json.example ".mcp.json.example")
| |
[CHANGELOG.md](/a-funk/sharkclean-mcp/blob/main/CHANGELOG.md "CHANGELOG.md")
| [CHANGELOG.md](/a-funk/sharkclean-mcp/blob/main/CHANGELOG.md "CHANGELOG.md")
| |
[CONFIRMED_MODELS.md](/a-funk/sharkclean-mcp/blob/main/CONFIRMED_MODELS.md "CONFIRMED_MODELS.md")
| [CONFIRMED_MODELS.md](/a-funk/sharkclean-mcp/blob/main/CONFIRMED_MODELS.md "CONFIRMED_MODELS.md")
| |
[CONTRIBUTING.md](/a-funk/sharkclean-mcp/blob/main/CONTRIBUTING.md "CONTRIBUTING.md")
| [CONTRIBUTING.md](/a-funk/sharkclean-mcp/blob/main/CONTRIBUTING.md "CONTRIBUTING.md")
| |
[LICENSE](/a-funk/sharkclean-mcp/blob/main/LICENSE "LICENSE")
| [LICENSE](/a-funk/sharkclean-mcp/blob/main/LICENSE "LICENSE")
| |
[README.md](/a-funk/sharkclean-mcp/blob/main/README.md "README.md")
| [README.md](/a-funk/sharkclean-mcp/blob/main/README.md "README.md")
| |
[SECURITY.md](/a-funk/sharkclean-mcp/blob/main/SECURITY.md "SECURITY.md")
| [SECURITY.md](/a-funk/sharkclean-mcp/blob/main/SECURITY.md "SECURITY.md")
| |
[pyproject.toml](/a-funk/sharkclean-mcp/blob/main/pyproject.toml "pyproject.toml")
| [pyproject.toml](/a-funk/sharkclean-mcp/blob/main/pyproject.toml "pyproject.toml")
| |
[uv.lock](/a-funk/sharkclean-mcp/blob/main/uv.lock "uv.lock")
| [uv.lock](/a-funk/sharkclean-mcp/blob/main/uv.lock "uv.lock")
| |
查看所有文件

仓库文件导航

- README
- 贡献指南
- MIT 许可证
- 安全

sharkclean-mcp

这是一个适用于 SharkClean / SharkNinja 扫地机器人的 MCP 服务器。它允许任何 MCP 客户端（如 Claude Code、Claude Desktop 等）以自然语言的方式，智能地启动清扫任务、清扫特定房间、让机器人返回基站以及检查状态。

非官方项目，与 SharkNinja 无关联，也未得到其认可。
所有命令都通过 SharkNinja 当前的云服务（“skegox”）执行，这与 SharkClean 应用使用的后端相同，因此机器人的行为与通过应用控制时完全一致，无需对硬件进行修改。
为何不使用 Ayla 云？广泛使用的 `sharkiq` SDK（以及基于它构建的 Home Assistant Shark IQ 集成）与 SharkNinja 的旧版 Ayla IoT 云进行通信。较新的机器人（如 Matrix、AI Ultra、Mach 2、RV2500+ 系列）已从 Ayla 迁移到 skegox 后端。在 Ayla 上，这些机器人显示为永久“离线”，房间地图冻结且陈旧，尽管应用可以正常控制它们。此服务器直接与 skegox 通信，因此它可以与 `sharkiq` 无法控制的较新机器人兼容。对 skegox API 的逆向工程得益于 shark2mqtt 项目。

工具

工具	功能
`list_robots`	列出账户中的机器人（名称、设备 ID）
`get_status`	获取实时状态：清扫/暂停/停靠、电池百分比、充电状态、功率模式、在线状态、错误信息
`start_cleaning`	全屋清扫，可选功率模式（`eco`/`normal`/`max`）
`list_rooms`	列出机器人当前地图中的房间（包含楼层 ID 和最后更新时间）
`clean_rooms`	仅清扫特定房间（根据实时地图进行验证）
`pause_cleaning` / `resume_cleaning` / `stop_cleaning`	运行控制
`return_to_dock`	让机器人返回基站充电/自清洁
`set_power_mode`	设置吸力：`eco`、`normal`、`max`
`locate_robot`	让机器人发出蜂鸣声

`start_cleaning` 和 `clean_rooms` 会先检查机器人是否在线，如果不在线则拒绝执行命令，避免命令无声无息地丢失。支持多机器人账户，每个工具都可以接受一个可选的 `robot` 参数（名称或设备 ID）。如果只有一个机器人，可以省略该参数。

设置

需要 uv 和 Python ≥ 3.10。

git clone https://github.com/a-funk/sharkclean-mcp
cd sharkclean-mcp
uv sync
cp .env.example .env # 添加您的 SharkClean 应用电子邮件和密码
uv run shark-mcp-auth # 一次性浏览器登录（见下文）
uv run shark-mcp-doctor # 确认：打印您的机器人和当前房间地图

一次性登录 (`shark-mcp-auth`)

SharkNinja 的 Auth0 租户阻止无头密码登录，因此首次登录需要在浏览器中使用 SharkClean 应用的 PKCE 流程：
1. `shark-mcp-auth` 会打开真正的 SharkClean 登录页面。
2. 登录。浏览器随后会尝试重定向到 `com.sharkninja.shark://...`，通常会显示错误、空白页面或“打开 SharkClean？”对话框，这是正常现象。
3. 复制完整的 `com.sharkninja.shark://...` URL（从地址栏、浏览器历史记录或开启“保留日志”的 DevTools 网络标签中获取），并在提示处粘贴。
完成以上步骤即可。令牌会缓存到 `~/.config/shark-mcp/tokens.json`（权限模式为 `600`）并自动刷新，之后无需再使用浏览器登录。有关凭证处理方式，请参阅 SECURITY.md。

在 MCP 客户端注册

-Claude Code（用户级）：

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

或者将 `.mcp.json.example` 复制为 `.mcp.json`，设置绝对路径，Claude Code 在打开此目录时会自动识别。
-Claude Desktop：将以下内容添加到 `claude_desktop_config.json` 中：

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

凭证来自环境变量或 `.env` 文件：`SHARKCLEAN_EMAIL`、`SHARKCLEAN_PASSWORD`，可选的 `SHARKCLEAN_REGION=eu`。

示例提示

- “启动最大功率清扫。”
- “清扫厨房和客厅。”
- “扫地机器人清扫完了吗？电池还有多少？”
- “让机器人返回基站。”

命令行控制

除了 MCP 服务器，`shark-mcp-rc` 可以在 shell 中控制机器人（适用于脚本或定时任务）：

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 # 单元测试（模拟机器人，不进行云调用）
uv run shark-mcp # 在标准输入输出上运行服务器
uv run shark-mcp-doctor # 针对云进行实时端到端检查

请参阅 CONTRIBUTING.md。如果您的机器人可以正常工作，请将其添加到 CONFIRMED_MODELS.md 中。

注意事项和限制

- 认证：一次性浏览器登录 (`shark-mcp-auth`) 会生成一个 Auth0 刷新令牌，缓存到 `~/.config/shark-mcp/tokens.json`。服务器会使用该令牌生成短期的 skegox id_token。SharkNinja 的 Auth0 租户会轮换刷新令牌，因此服务器会在每次刷新时保存轮换后的令牌。如果出现 `invalid_grant` 错误，请重新运行 `shark-mcp-auth`。
- 无头/脚本化密码登录会被 Auth0 的机器人检测机制阻止（“可疑请求需要验证”），浏览器流程是可靠的登录方式。
- 房间定位 (`clean_rooms`) 需要机器人有完整的地图，较旧的不支持房间识别的型号将无法列出房间。
- 这是一个非官方项目，基于社区的逆向工程构建。SharkNinja 可能随时更改后端。