bosch-flow-mcp

bosch-flow-mcp

适用于 Bosch eBike Flow（Smart System / BES3）的 MCP 服务。跟踪电池健康状况、充电周期、组件版本、维修历史、实时电量，以及每次骑行的活动数据（距离、海拔、功率、助力模式、CO2）。

免责声明

这是一个非官方的社区项目。它与 Robert Bosch GmbH、Bosch eBike Systems 或 SingleKey ID 无关联，也未获得其授权或认可。“Bosch”“eBike Flow”及相关标记均属于其所有者，此处仅用于描述互操作性。

• 使用你自己的 Bosch eBike Flow 账户登录（通过标准 SingleKey ID 登录），并且只读取你自己的数据。它是只读的——绝不会修改你的自行车、电池或账户。
• 使用官方 Bosch eBike Flow 应用所用的同一公开 OAuth 客户端（one-bike-app，PKCE）。不会提取、绕过或规避任何凭据、机密或保护措施——此处的每个标识符都已有公开文档。
• 如果你提供自己的 EU Data Act API 凭据，则会使用官方 Data Act API。否则，会使用你手机上已有应用所用的同一 API，通过你的登录信息进行查询。
• 这是一个未公开文档的非官方接口。如果 Bosch 更改其系统，接口可能随时变更或停止工作。
• 你有责任确保自己的使用方式符合所在司法管辖区内 Bosch 和 SingleKey ID 的服务条款。
• 根据 GPLv3+ 按“原样”提供，不附带任何保证（参见 LICENSE）。使用风险由你自行承担。

功能

• 随时间记录电池状态快照（充电周期、输送能量、退化趋势）
• 组件和固件版本（驱动单元、电池、ConnectModule、车载主机、遥控器、ABS）
• 维修记录历史和软件更新日志（仅限 EU Data Act 客户端）
• 通过移动 API 获取 ConnectModule 的实时电量
• 电池容量测试结果（仅限 EU Data Act 客户端）
• 每次骑行的活动数据：距离、海拔、速度、踏频、测得的骑行者功率、卡路里、骑行者与电机的能量占比、助力模式分布、CO2、ABS 事件，以及逐点记录的 GPS/速度/海拔/功率轨迹
• 按需自动同步——工具无需 cron 任务即可获取最新数据

要求

• Python 3.13+（已在 Linux、macOS 和 Windows 上使用 3.13 和 3.14 进行测试，并通过 CI 验证）
• uv（推荐）或 pip
• Bosch eBike Flow 账户（免费，可在 Bosch eBike Flow 应用中注册）
• 已在应用中注册的 BES3 Smart System 电动自行车

安装

pip install bosch-flow-mcp

也可以使用 uvx bosch-flow-mcp 运行，无需安装。如需从克隆版本进行开发：

git clone https://github.com/partymola/bosch-flow-mcp
cd bosch-flow-mcp
uv venv --python 3.13 .venv
uv pip install -e .

认证

.venv/bin/bosch-flow-mcp auth

将在浏览器中打开 Bosch 登录页面。认证流程使用带 PKCE 的 one-bike-app 公共客户端——无需 API 密钥或注册，只需使用你的 Bosch Flow 账户。

**重要：**登录前，请打开浏览器开发者工具（F12）并切换到 Network 标签页。 登录后，浏览器会重定向到 iOS URI（onebikeapp-ios://），桌面浏览器无法打开该 URI。从开发者工具中复制完整的重定向 URL（在 oauth2redirect 条目上右键 > Copy URL），然后粘贴到提示符中。

令牌会保存到 config/bosch_tokens.json，并通过 offline_access 自动刷新。

**EU Data Act 用户：**如果你已注册自己的 euda 客户端，并将其 ID 填入 config/bosch_config.json，auth 会改用该客户端——它会打开浏览器，并通过本地 http://localhost:4200 回调自动完成认证，无需使用开发者工具。

同步

.venv/bin/bosch-flow-mcp sync                     # all data types
.venv/bin/bosch-flow-mcp sync --types bikes,batteries

数据类型：bikes、batteries、components、service、software_updates、capacity。

获取你的数据并将其保存在本地。数据来源取决于你的登录方式：

• 标准 Bosch eBike Flow 账户（默认）会从移动应用 API读取自行车、电池、组件、 当前固件和实时电量状态——适用于任何账户，包括非 EU 账户。
• 保养手册历史记录、软件更新历史记录和容量测试仪结果仅来自 EU Data Act API， 这需要你在 Bosch Data Act portal 注册自己的 euda 客户端。使用标准登录时，这些类型会显示 unavailable（并附带说明），而非 静默返回空结果；对于在 EU 以外注册的账户，Data Act API 不会返回任何数据。

你也可以使用 bosch_sync MCP 工具，或依赖自动同步（如果数据已过期，每个 get_* 工具 都会触发同步）。

运行 bosch-flow-mcp --version 可打印已安装的软件包版本。

在 Claude Code 中注册

claude mcp add -s user bosch-flow -- /full/path/to/bosch-flow-mcp/.venv/bin/bosch-flow-mcp

然后可以向 Claude 提问，例如：

• “我的自行车今年的电池健康状况如何？”
• “按月显示充电循环趋势”
• “我的驱动单元使用的固件版本是什么？”
• “我的自行车有过任何保养记录吗？”
• “我这周骑了多远？骑行强度如何？”

可用工具

工具	描述
bosch_sync	同步一种或多种数据类型（默认：全部）
bosch_get_bikes	列出已注册的自行车
bosch_get_bike	获取单辆自行车的完整详情
bosch_get_batteries	电池快照——最新快照或历史范围
bosch_get_soc	从 ConnectModule 获取实时电量状态
bosch_get_capacity	电池容量测试仪结果（仅限 EU Data Act 客户端）
bosch_get_components	获取组件及其零件编号和固件版本
bosch_get_service_records	保养手册条目（仅限 EU Data Act 客户端）
bosch_get_software_updates	软件更新历史记录（仅限 EU Data Act 客户端）
bosch_battery_trends	按周期查看充电循环和能量趋势
bosch_get_activities	指定日期范围内每次骑行的摘要（距离、海拔、功率、模式、CO2）
bosch_get_activity_detail	单次骑行的逐点轨迹（GPS/速度/海拔/踏频/功率）

API 致谢

此服务以 Bosch Mobile API（obc-rider-profile.prod.connected-biking.cloud） 作为主要数据源，使用 rider-activity API （obc-rider-activity.prod.connected-biking.cloud）获取每次骑行的数据，并可选支持 Data Act API（api.bosch-ebike.com）以访问其他端点。

认证使用 one-bike-app 公共客户端（与 Bosch eBike Flow 移动应用使用的 OAuth 客户端相同）。认证方案参考了 marq24/ha-bosch-ebike-flow Home Assistant 集成和 open-ebike/open-ebike-backend 项目的文档。

配置

变量	默认值	描述
BOSCH_FLOW_MCP_DB_PATH	软件包根目录中的 bosch_flow.db	SQLite 数据库路径
BOSCH_FLOW_MCP_CONFIG_DIR	软件包根目录中的 config/	存储令牌和客户端配置的目录

数据安全

• OAuth 令牌在 POSIX 系统上以 0600 权限创建；Windows 会忽略此权限，并通过继承的 ACL 控制访问；令牌文件和 bosch_flow.db 均已加入 git 忽略列表。

• 预提交钩子（scripts/check-no-data.sh）会阻止提交数据库文件、config/ 下的文件以及大文件。它不会读取文件内容。克隆后请安装：

  ln -sf ../../scripts/check-no-data.sh .git/hooks/pre-commit
  

• 测试使用临时 SQLite 数据库和虚构标识符，仓库中不会出现真实的自行车或账户数据。

贡献

开发环境设置、测试工作流和预提交钩子请参阅 CONTRIBUTING.md。变更记录见 CHANGELOG.md。

许可证

GPLv3+。请参阅 LICENSE。