内容
# nightscout-mcp
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，允许LLM（Claude Desktop，Claude Code，任何MCP客户端）从个人 [Nightscout](https://github.com/nightscout/cgm-remote-monitor) 实例中读取葡萄糖、治疗和衍生分析数据。
[](https://www.python.org/downloads/)
[](./LICENSE)
[](https://github.com/ColebyPearson/nightscout-mcp/actions/workflows/ci.yml)
[](https://modelcontextprotocol.io)
## ⚠️ 不是医疗设备
该工具读取CGM数据并将其显示给LLM。**它不是医疗设备，不提供临床建议，不应用于做出治疗决策。** Nightscout本身表示它“目前不尝试遵守HIPAA隐私合规”，并且仅用于教育目的。请自担风险使用。
## 您获得的功能
**44个只读MCP工具**，涵盖实时数据、历史数据和 analytics 。LLM可以询问诸如 *"我的当前血糖是多少，胰岛素储备是多少?"* 或 *"这个星期有超过一半的早晨出现了黎明现象吗?"* 并获得由实际Nightscout查询支持的结构化答案。
### 读取工具（10）
| 工具 | 返回 |
|---|---|
| `health_check` | NS可达性 + 版本 + 单位 |
| `get_current_glucose` | 最新SGV + 趋势箭头 + 新鲜度 + 与前一次的差异 |
| `get_glucose_history` | 时间序列SGV在一个窗口内 |
| `get_glucose_stats` | TIR / TBR / TAR / SD / CV / GMI（A1C估计）在一个窗口内 |
| `get_treatments` | 推注 / 碳水化合物 / 基线 / 注释 |
| `get_iob_cob` | 胰岛素和碳水化合物储备来自 `devicestatus` |
| `get_current_profile` | 基线计划 / ISF / CR / 目标 / DIA / 时区 |
| `get_device_status` | 泵 / 环路 / 上传者状态（环路数据的分级优先级） |
| `get_server_status` | Nightscout版本，状态，配置单位 |
| `search_treatments` | 笔记 / 事件类型的自由格式子字符串搜索 |
### 分析工具（11）
| 工具 | 返回 |
|---|---|
| `get_daily_report` | 一日统计 + 治疗总数 + 过滤用户注释 |
| `compare_periods` | 侧边栏统计与纯英语增量总结 |
| `analyze_meal` | 进食前血糖 / 峰值 / 到峰时间 / 上升 / 恢复 / 注释 |
| `overnight_analysis` | 漂移 / 最小/最大值 / 时间低于 / 黎明上升 / 平坦度 |
| `detect_patterns` | 反复夜间低血糖，黎明现象，餐后峰值 |
| `hypoglycemia_episodes` | **共识低血糖事件**（Battelino 2019 / ATTD ≥15-min <70）：每事件持续时间 / 最低值 / 1-2级 / 夜晚 / 救援碳水化合物链接 + CGM活动百分比 |
| `insulin_sensitivity_check` | **现实世界ISF来自修正推注结果** + 与配置文件比较 |
| `effective_isf_check` | 现实世界ISF与AAPS动态ISF（每周期`variable_sens`）比较，按预推注血糖段分层 |
| `carb_ratio_check` | 现实世界CR来自进食推注结果 + 与配置文件比较 |
| `glucose_at_time` | 单个时间点SGV，±N分钟容差 |
| `compression_low_analysis` | 疑似传感器压缩伪影（假低） |
### 研究级临床指标（12）
来自临床文献的规范CGM指标，从现有的Nightscout数据中计算。按照2026-05-24的深度研究审查的儿科闭环T1D分析添加。所有公式都被引用；模块文档字符串中有参考文献。
| 工具 | 返回 | 参考文献 |
|---|---|---|
| `glycemia_risk_index` | GRI + 低血糖 / 高血糖组件分解 | Klonoff *JDST* 2023;17:1226 |
| `bg_risk_indices` | LBGI / HBGI / ADRR与风险带 | Kovatchev *Diabetes Care* 1998;21:1870 + 2006;29:2433 |
| `glucose_variability_metrics` | MAGE, MODD, J-index, M-value, GVP, CONGA-{1h,2h,4h}, COGI, CV | Service 1970, Molnar 1972, Schlichtkrull 1965, McDonnell 2005, Peyser 2018, Leelarathna 2020 |
| `time_in_range_with_ci` | TIR / TBR / TAR与Wilson二项式95％CI按段 | Battelino *Diabetes Care* 2019;42:1593 |
| `data_sufficiency_report` | 有数据天数 / CGM活动百分比 / 最长间隙 + `meets_agp_consensus`标志（≥14天，≥70％活动） | Battelino *Diabetes Care* 2019;42:1593 |
| `per_meal_period_tir` | 按早餐 / 午餐 / 晚餐 / 夜间 / 下午 / 晚上划分的TIR | （组成） |
| `ambulatory_glucose_profile` | AGP样式的5/25/50/75/95百分位带按小时 | Battelino 2019 AGP共识 |
| `bolus_event_residuals` | 每推注实现的ISF与AAPS预测的ISF，按血糖段和时间划分 | （上述内容的组合） |
| `change_points_bg` | 在每小时平均血糖上进行窗口平均偏移变化点检测，带有配置文件更改注释 | Page 1954（CUSUM家族） |
| `change_points_tdd` | 每天总日剂量的相同变化点检测（捕捉青春期/疾病/站点变化） | |
| `dia_fit_estimate` | AAPS指数IOB曲线的探索性拟合观察推注残差 → 建议DIA + 峰值 | oref0指数 / AAPS Oref |
| `clinic_packet` | AGP级30天markdown报告：CGM覆盖头，TIR + Time-in-Tight-Range + GRI + LBGI/HBGI，共识低血糖事件计数，胰岛素/碳水化合物总结，嵌入式AGP中位数+ IQR带，每日配置文件，每餐周期，变化点 - 准备好与内分泌团队分享 | Battelino 2019 |
### 组合工具（6）
更高层次的工具，将指标套件组合成可行的输出。
| 工具 | 返回 | 参考文献 |
|---|---|---|
| `daily_synthesis` | 结合跨工具临床汇总（统计 + IOB/COB + ISF/CR + 模式）在一个窗口内，并附有纯英语叙述 | （组成） |
| `dynisf_adjustment_recommender` | 根据观察到的每个血糖段ISF残差推荐动态ISF调整因子。区分BG曲线阻尼和统一AF误差，按深度研究决策树划分。 | 2026-05-24深度研究报告关键发现#1 |
| `consensus_target_audit` | 与Battelino 2019 / ISPAD 2022 / Klonoff 2023 / Kovatchev阈值的单次通过/失败审计；`population`选择目标集（`standard` / `older_high_risk` / `pregnancy_t1d`，孕期范围63–140） | Battelino 2019，ISPAD 2022 |
| `settings_change_attribution` | 对于窗口中的每个配置文件切换事件：切换前后的TIR / TBR / GRI，并对更改进行Benjamini-Hochberg FDR校正 | BH FDR（Benjamini＆Hochberg 1995） |
| `agp_markdown_render` | 带有ASCII IQR带可视化的markdown渲染AGP | Battelino 2019 AGP共识 |
| `time_period_compare` | 两个窗口的TIR / TBR<54 / GRI / LBGI / HBGI / CV / GMI并排显示，带有95％CI和统计显著性标志 | Wilson 1927二项式CI |
### AAPS历史工具（5）
只读访问本地SQLite存储的AAPS设置快照（由配套的`aaps-history-ingest`服务填充，该服务监视Google Drive文件夹中的AAPS加密导出，使用OS密钥环中的密码解密，并存储快照+更改事件）。
当未配置摄取服务时，每个工具返回一个温和的空结果，并附有说明设置步骤的注释 - 这些工具是可选的基础设施，构建在Nightscout侧的工具之上。
| 工具 | 返回 |
|---|---|
| `aaps_history_status` | 数据库存在， 快照数量， 覆盖日期范围 |
| `aaps_setting_at` | 在给定时间点解析的设置值，从最近的前一个快照 |
| `aaps_setting_history` | 在窗口内检测到的单个设置的所有更改 |
| `aaps_settings_diff` | 两个时间戳之间更改的所有设置 |
| `aaps_log_user_entries` | AAPS日志存档中的USER ENTRY记录（当自动日志导出Track 4发货时填充） |
数据库位置通过`AAPS_INGEST_DB_PATH`环境变量解析，默认为`C:\Repos\aaps-history-ingest\data\ingest.sqlite`。
## 示例：LLM实际看到的内容
`insulin_sensitivity_check(days=14)`针对个人Nightscout实例返回类似：
```json
{
"sample_count": 37,
"derived_isf_mgdl_per_unit": 304.7,
"derived_isf_mmol_per_unit": 16.9,
"profile_isf_mmol_per_unit": 14.0,
"ratio_derived_over_profile": 1.21,
"confidence": "high",
"recommendation": "Derived ISF suggests you're MORE sensitive than your profile says (each unit drops you further). Consider lowering profile ISF or reviewing for overcorrections."
}
```
`detect_patterns(days=7)`显示类似：
```json
{
"type": "post_meal_spike",
"occurrence_count": 7,
"avg_value_mgdl": 73.6,
"description": "Rapid rises >50 mg/dL within 30 min seen on 7 of 7 days. Bolus-to-eat timing may benefit from a longer pre-bolus."
}
```
这些不是通用的 - 它们是从用户的实际结果计算的，而不是他们的配置文件声明。
## 为什么存在
野生中有几个其他的Nightscout MCP：
- **`adminpb/Nightscout-MCP`** （TypeScript）- 24个工具，但没有可见的测试
- **`easyweek/mcp-nightscout`** （Python，HTTP + Docker）- 构建用于共享/远程部署，包括破坏性写入，如`remove_treatment`
- **`nightscout/nocturne`** （C＃/.NET）- 第一方但针对未来的Nocturne平台，而不是v15
该项目故意选择不同的位置：
| 轴 | 该项目 |
|---|---|
| 传输 | **stdio** - 没有暴露的网络表面 |
| 认证 | **仅限令牌** - 拒绝`API_SECRET`（最小权限） |
| 写入 | **无** - 对个人/教育用途而言肯定更安全 |
| 测试 | **230+通过** 包括跨工具令牌泄漏回归 |
| 默认单位 | **mmol/L** （可覆盖）- 每个有效载体都包含两者 |
| 分析 | **现实世界ISF** ，压缩低检测，重复模式检测 |
## 安装
```bash
git clone https://github.com/ColebyPearson/nightscout-mcp
cd nightscout-mcp
uv sync
```
（计划发布PyPI - 请参见[PLAN.md §10](./PLAN.md).）
## 配置
1. Nightscout → **Admin Tools → Subjects**，使用 **`readable`** 角色（例如`mcp-reader`）创建令牌。
2. 复制`.env.example`到`.env`并填写：
```ini
NIGHTSCOUT_URL=https://your-nightscout.example.com # 必须是https://
NIGHTSCOUT_TOKEN=mcp-reader-xxxxxxxxxx # 永远不要使用API_SECRET
NIGHTSCOUT_UNITS=mmol/L # 或mg/dL
```
3. **保护文件。** 您的令牌允许任何人读取您的CGM数据。 与`~/.ssh/`相同的安全预防措施:
```bash
chmod 600 .env # macOS / Linux
icacls .env /inheritance:r /grant:r "%USERNAME%:R" # Windows PowerShell
```
`.env`从`.gitignore:2`被gitignore - 它不会被意外提交。
## 运行
### MCP Inspector（开发/手动测试）
```bash
uv run mcp dev src/nightscout_mcp/server.py
```
### Claude Desktop
在`claude_desktop_config.json`中添加（macOS：`~/Library/Application Support/Claude/`，Windows：`%APPDATA%\Claude\`）：
```json
{
"mcpServers": {
"nightscout": {
"command": "uv",
"args": ["--directory", "/abs/path/to/nightscout-mcp", "run", "nightscout-mcp"],
"env": {
"NIGHTSCOUT_URL": "https://you.nightscout.example",
"NIGHTSCOUT_TOKEN": "mcp-reader-xxxxxxxxxx",
"NIGHTSCOUT_UNITS": "mmol/L"
}
}
}
}
```
重启Claude Desktop。 44个工具出现在 🔌菜单下。
### Claude Code
```bash
claude mcp add nightscout --env NIGHTSCOUT_URL=https://… --env NIGHTSCOUT_TOKEN=… -- uv --directory /abs/path/to/nightscout-mcp run nightscout-mcp
```
## 安全模型
该项目保护您的数据：
- **`NIGHTSCOUT_URL`必须是`https://`** - 否则拒绝启动。
- **令牌从未进入LLM上下文。** 它仅用作出站HTTPS调用的`?token=…`查询参数。 工具响应仅包含派生数据。
- **令牌从不出现在日志中。** httpx记录器上的正则表达式筛选器在发出之前将`token=…` ， `Bearer …`和`api-secret: …`值替换为`***` 。 有一个单元测试断言这一点。
- **令牌从未出现在任何工具响应中。** 有一个跨工具回归测试，设置了一个金丝雀令牌，调用每个工具，JSON序列化响应，并断言金丝雀不会出现。
- **设计上只读。** 写入工具不被导入。 即使设置`NIGHTSCOUT_ALLOW_WRITES=true`，也不会发生任何操作。
- **默认情况下仅限本地。** stdio传输意味着没有监听端口。 您的数据保留在您的机器上 + 您的Nightscout主机上。
该项目**不**执行：
- 在静止状态下加密您的`.env`（使用OS文件权限）
- 检测令牌泄露（如果您怀疑泄漏，请通过Admin Tools旋转）
- 取代临床判断（它不是医疗设备）
## 开发
```bash
uv sync --extra dev
uv run pytest # 完整的测试套件
uv run pytest tests/test_analytics.py # 仅分析
uv run ruff check . # 校验
```
架构： [PLAN.md](./PLAN.md)。 问题驱动的工作流，具有自我审查的PR。
## 许可证
[MIT](./LICENSE)。 Nightscout本身是 [AGPL-3.0](https://github.com/nightscout/cgm-remote-monitor/blob/master/LICENSE) - 该项目使用其HTTP API，但不包含或重新分发其代码。
## 致谢
- [Nightscout基金会](https://nightscout.github.io/) 和更广泛的 **#WeAreNotWaiting** 社区 - 为构建该MCP所依赖的平台。
- [`adminpb/Nightscout-MCP`](https://github.com/adminpb/Nightscout-MCP) - TypeScript先前艺术，影响了多个工具名称。
- [`easyweek/mcp-nightscout`](https://github.com/easyweek/mcp-nightscout) - JSON日志擦除模式。
- [`amansk/librelink-mcp-server`](https://github.com/amansk/librelink-mcp-server) - “数据从未离开您的机器”的凭证安全框架。
- [官方MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) 和FastMCP装饰器API。
- Bergenstal等人， *Diabetes Care* 2018; 41:2275–2280 - `get_glucose_stats`中使用的GMI公式。
