Skip to main content
Glama

dalingring-mcp

A Model Context Protocol server for DalingRing smart rings — bring your own account, read your own data, analyze it locally.

把 DalingRing 智能戒指的数据接进 Codex / Claude Desktop / Cursor 等支持 MCP 的 AI 工具, 或用自带的 web 面板直接看图表。所有数据只存在本机。

非官方第三方客户端。做的事情等价于你在手机上打开 App 看到的内容,只是把数据落成本地 SQLite,让 AI 能算、能比、能画。


dashboard


目录


Related MCP server: oura-mcp-server

它解决什么问题

手机 App 只能看,不能问。

你想知道的

App 能不能回答

我最近睡眠是不是在变差?

给一张图,自己判断

睡得少的那几天,压力是不是更高?

不提供

把 9 月和 10 月的静息心率对比一下

只能手动翻

报告说我 HRV 偏低,那我实际 HRV 是多少?

要跨两个页面自己找

接上 MCP 之后这些都变成一句话:

你:帮我看看这个月睡眠和压力的关系
模型:(sync → analyze_sleep → analyze_stress → correlate)
      30 天里睡眠时长均值 317 分钟,低于 7 小时的有 18 天;
      压力均值 44,高压日集中在周三周四;
      两者相关系数 -0.62,中等负相关——睡得短的那几天压力确实更高。

系统架构

┌──────────────────────┐                    ┌──────────────────────┐
│  AI 工具              │   MCP (stdio)      │  MCP server          │
│  Codex / Claude       │◀──────────────────▶│  server.py           │
│  Cursor / Cline       │   23 个 tools       │  23 tools            │
└──────────────────────┘                    └──────────┬───────────┘
                                                       │
┌──────────────────────┐                               │
│  浏览器               │   HTTP :8770                  │
│  可视化面板            │◀──────────────────┐          │
└──────────────────────┘                    │          │
                                            ▼          ▼
                                   ┌────────────────────────────┐
                                   │  web/server.py  9 个 API    │
                                   └────────────┬───────────────┘
                                                │
                     ┌──────────────────────────┴─────────────────────────┐
                     ▼                                                    ▼
          ┌────────────────────┐                              ┌────────────────────┐
          │  client.py          │   只读 GET/POST               │  store.py           │
          │  请求头 + token 注入 │ ───────────────────────────▶ │  SQLite 本地缓存     │
          └────────────────────┘   api.dalingring.com           └─────────┬──────────┘
                                                                          ▼
                                                                 ┌────────────────────┐
                                                                 │  analyze.py         │
                                                                 │  report_parse.py    │
                                                                 │  纯函数统计 / 报告解析 │
                                                                 └────────────────────┘

一条设计主线:云端数据只拉一次,之后所有计算都在本地。

sync(days=90)   →   约 450 次请求   →   SQLite 落盘
                                          ↓
                        analyze_* / correlate / report_parse
                                          ↓
                     纯 SQL 查询 + 标准库统计,零请求、断网可用、无限次

这是它和"随手写个脚本"的本质区别——你问十遍「这月对比上月」,服务器一次都不用碰。


快速开始

环境

  • Python 3.10+

  • 一个能登录 DalingRing App 的手机号(密码或短信验证码)

安装

git clone https://github.com/Swellyhow/dalingRing-R-G.git
cd dalingRing-R-G

# 方式一:安装为包
pip install -e .

# 方式二:不安装,直接用 PYTHONPATH(下面配置里就是这么写的)

验证

# Linux / macOS
PYTHONPATH=src python -m dalingring_mcp

# Windows PowerShell
$env:PYTHONPATH="src"; python -m dalingring_mcp

进程挂在那儿等输入就对了(stdio 模式,没有输出是正常现象)。

接进 AI 工具

[mcp_servers.dalingring]
command = "python"
args = ["-m", "dalingring_mcp"]
env = { PYTHONPATH = "/absolute/path/to/dalingRing-R-G/src" }
{
  "mcpServers": {
    "dalingring": {
      "command": "python",
      "args": ["-m", "dalingring_mcp"],
      "env": { "PYTHONPATH": "/absolute/path/to/dalingRing-R-G/src" }
    }
  }
}
{
  "mcpServers": {
    "dalingring": {
      "command": "python",
      "args": ["-m", "dalingring_mcp"],
      "env": { "PYTHONPATH": "/absolute/path/to/dalingRing-R-G/src" }
    }
  }
}

第一次使用

你:登录我的 DalingRing 账号,手机号 1xxxxxxxxxx,密码 xxxxxx
模型:调 login_password → token 存到 ~/.dalingring/token.json

你:同步最近 90 天的数据
模型:调 sync(days=90) → 拉取睡眠/心率/血氧/HRV/压力/报告

你:我最近睡眠怎么样
模型:调 analyze_sleep(30) → 给结论

工具清单(23 个)

认证

工具

说明

login_password(mobile, password)

手机号 + 密码,优先走 v2 登录(能读新版报告),失败回退 v1

login_send_code(mobile)

发短信验证码(服务端有频率限制,别连点)

login_with_sms(mobile, code)

验证码登录

whoami()

当前账号 + 绑定设备

logout()

清除本地 token

同步

工具

说明

sync(days=30, end_date=None)

拉最近 N 天数据入库,end_date 可指定历史某天往前拉

sync_reports(limit=20)

下载报告全文到本地

查询

工具

说明

数据源

profile()

昵称/性别/生日/身高体重/设备 MAC

云端

daily_snapshot(date)

某天全部指标快照

云端

trends(days)

9 个心脏趋势指标

云端

sleep(days)

睡眠明细

本地

heart_rate(days)

心率/静息心率/HRV/血氧

本地

stress(days)

压力值

本地

reports(limit)

报告列表

本地

report_detail(report_id)

报告原始 JSON(自动选 v1/v2)

云端

report_markdown(report_id)

渲染成 App 里那份报告的排版

云端→解析

report_structured(report_id)

报告结构化字段

云端→解析

分析(全部离线)

工具

说明

analyze_sleep(days)

均值/中位数/标准差/趋势斜率/最差日/不足 7 小时天数

analyze_heart(days)

日均心率、静息心率趋势、HRV 分布

analyze_stress(days)

日均、波动、高压异常日(>2σ)

analyze_overview(days)

三块合一

correlate(a, b, days)

皮尔逊相关系数 + 强弱判定

export_json(kind, days)

导出 JSON 供模型直接读

可用指标名:sleep_duration sleep_score heart_rate_avg heart_rate_rest hrv_avg spo2_avg stress_avg stress_week_avg sleep_week_duration sleep_week_score


可视化面板

不想跟模型对话、只想看图表的时候:

python web/server.py               # http://127.0.0.1:8770
python web/server.py --port 9000

区块

内容

顶栏

昵称、性别年龄、设备型号、MAC、绑定状态

指标卡

睡眠时长 / 静息心率 / HRV / 压力,各带「相对均值」的差值与涨跌色

趋势

6 张 SVG 折线,可切 7/30/90 天

指标对比

双 Y 轴折线,任选两个指标叠加 + 皮尔逊相关系数

健康报告

分数环 + 检测时间,点开是完整报告

数据概况

库路径、原始行数、指标行数、报告数、日期范围

report

深链:http://127.0.0.1:8770/?report=<reportId> 直接打开某份报告。

技术选择上刻意保持零依赖:后端 http.server,前端原生 JS + 手写 SVG 折线, 不引 ECharts/CDN。断网也能用。

指标对比为什么值得单独做

单指标趋势只能看"自己在变好还是变差",看不出"两件事有没有关系"。对比面板把两个指标 放到同一张图(左右各一根 Y 轴、实线 + 虚线区分),下面直接给结论:

r = -0.62 负相关 · 中等 样本 30 天

样本不足 8 天时不会硬算,而是明确告诉你「只有 2 天共同数据,至少需要 8 天」—— 这是 analyze.correlate 的保护,避免从两三个点编出结论。

API

方法

路径

作用

GET

/api/summary

账号 + 最新指标 + 全部序列 + 分析摘要

GET

/api/reports

报告列表

GET

/api/report?id=

单份报告(结构化 + markdown)

GET

/api/correlate?a=&b=&days=

两指标相关性 + 两条原始序列

GET

/api/sync/status

同步进度

POST

/api/sync

触发同步 {"days": 30}

POST

/api/login

页面里直接登录 {"mobile","password"}

GET

/api/health

健康检查


报告解析

App 里的「健康评估报告」是 report/v2/find 返回的一坨嵌套 JSON。report_parse.py 按 App 的渲染顺序把它拆成 8 段:

intro                     标题 + 描述
overallAssessment         总分 / 状态名 / 一句话概述
healthSignalObservations  健康信号卡(脾胃负担、睡眠恢复…)
vitalSigns                生命体征,分 3 组:心肺与循环 / 恢复与压力 / 日常状态
tcmConstitution           中医体质(主体质、脉象、舌象四要素)
constitutionRelatedTrends 体质相关趋势(分数 + 优先级 + 依据)
dualSystemInterpretation  综合建议 + 行动建议 + 三餐饮食建议
disclaimer                免责声明

用途

工具

返回

贴给用户看

report_markdown(report_id)

3000+ 字 markdown

给模型算

report_structured(report_id)

结构化字段

有了这两个工具,就能问出 App 问不出来的问题:

我三份报告里气虚质是变好还是变差?
把最近两份报告的体质相关趋势做个 diff
报告说我 HRV 偏低,那我实际 HRV 是多少?

新版报告必须用 login/v2 拿 token 才能访问 report/v2/find(type=0 走密码, type=1 走验证码)。login_password 已默认走 v2,失败自动回退 v1。


适用场景

适合:

  • 想批量导出自己的健康数据做长期跟踪

  • 想让 AI 帮忙做趋势分析、相关性分析,而不是每张图自己看

  • 多个季度 / 多份报告的对比(体质变化、指标漂移)

  • 把数据接进自己的看板、Notion、Excel

  • 学习 MCP server 怎么写(代码量小、结构完整、有真实数据)

不适合:

  • 想绕过 App 做破解或改数据——本项目只有读接口

  • 想要实时数据——它是同步式,不是流式

  • 多用户服务端部署——设计上是单机单账号工具


功能限制

诚实列出,避免踩坑:

限制

说明

数据取决于戒指

没戴、没同步、没充电,云端就是空的。sync 返回 metrics_written: 0 不代表工具坏了

只有读接口

刻意没做写入(改体重、绑设备、删记录),避免误操作

服务端限流

captcha 对同一号码有明显频率限制,验证码登录失败要等 10 分钟以上

token 有时效

JWT 过期后需重新登录,whoami 会提示

不支持多设备

一次只能持有一个账号的 token;多账号靠 DALINGRING_HOME 隔离

依赖非公开接口

服务端一改接口就可能失效,见 路线图

不做数据校验

拿到什么就是什么,不纠正服务端的异常值(比如 HRV 显示 0)

协议版本

基于 mcp >= 2.0(MCPServer);1.x 会自动 fallback 到 FastMCP


路线图

  • MCP server,21 个基础工具

  • 报告解析(markdown + 结构化)

  • v2 登录与 v2 报告接口

  • 可视化面板(趋势 + 报告 + 对比)

  • 双 Y 轴指标对比 + 相关系数

  • 散点图 + 线性拟合

  • 批量补拉历史(指定起始日往回翻 90 天)

  • web 面板多账号切换

  • 报告时间序列(多份报告的体质分数排成曲线)

  • CSV / Excel 导出

  • 接口失效时的降级与告警


开发与测试

dalingring-mcp/
├── src/dalingring_mcp/
│   ├── config.py        环境变量与路径
│   ├── client.py        HTTP 层(请求头/token/重试/错误归一化)
│   ├── auth.py          登录 + token 落盘(JWT payload 解码)
│   ├── store.py         SQLite(raw / daily / reports 三张表)
│   ├── sync.py          批量拉取 + 指标抽取
│   ├── analyze.py       统计函数(无 pandas 依赖)
│   ├── report_parse.py  报告解析与渲染
│   └── server.py        MCP 工具定义 + 入口
├── web/
│   ├── server.py        面板后端(http.server)
│   └── static/          前端(原生 JS + SVG)
├── tests/fixtures/      脱敏后的报告样例
└── test_*.py            三个测试脚本
python test_smoke.py     # 协议层:list_tools + 调一个离线工具
python test_e2e.py       # 登录 → 同步 → 分析(需 DR_MOBILE / DR_PASSWORD)
python test_report.py    # 报告解析(需账号)

环境变量:

export DR_MOBILE=1xxxxxxxxxx
export DR_PASSWORD=xxxxxx

加一个新接口

  1. 在 client.py 或 sync.py 里加调用

  2. 在 store.save_daily() 里定一个指标名

  3. 在 analyze.py 里加一个 xxx_summary()

  4. 在 server.py 里加 @mcp.tool() 包一层

四步,没有别的魔法。


数据与隐私

  • token 存 ~/.dalingring/token.json,权限收到当前用户(POSIX 600 / Windows ACL)

  • 数据存 ~/.dalingring/data.sqlite3

  • 多账号:DALINGRING_HOME=~/.dalingring/alice python -m dalingring_mcp

  • 不会:代登录、缓存别人的 token、把数据发给任何第三方

  • 仓库里不含任何真实账号、token 或健康数据;测试用 tests/fixtures/ 下的脱敏样例


许可证

MIT © 2026 dalingring-mcp contributors

仅对本项目代码授权。DalingRing 品牌、App、服务端接口及其返回数据的所有权归原权利人, 不在此授权范围内。


免责声明

本项目是非官方的个人数据导出工具,依赖公开的客户端接口。使用者需自行确保:

  • 对所操作的账号有合法使用权

  • 导出的健康数据按当地法规妥善保管

  • 不用于商业分发或规避服务条款

健康数据仅供参考,不构成医学诊断。作者不对数据准确性及使用后果负责。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      B
      maintenance
      Local-first MCP server that connects AI agents to your Oura Ring readiness, sleep, activity, and HRV data. Tokens never leave your machine.
      27
      175 npm
      6
      MIT
    • A
      license
      B
      quality
      B
      maintenance
      Downloads all your Garmin health and fitness data into a local SQLite database and exposes 45 MCP tools for AI analysis, enabling assistants to query sleep, training load, HRV, and more.
      48
      99 PyPI
      173
      AGPL 3.0
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to sync WHOOP recovery, sleep, workouts, cycles, and body-measurement data into a local Postgres database and query it through fast, offline-capable MCP tools without repeatedly hitting WHOOP API rate limits.
      10
      MIT