<h1 align="center">🩸 Nightscout MCP Server</h1>

<p align="center"> <strong>Connect your Nightscout CGM data to any AI assistant via the Model Context Protocol.</strong> <br/> Real-time glucose · Treatments · Statistics · Pattern detection · Analytics · i18n </p>

<p align="center"> <a href="#-quick-start">Quick Start</a> • <a href="#-tools">Tools</a> • <a href="#-configuration">Configuration</a> • <a href="#-localization">i18n</a> • <a href="#-українською">Українською</a> </p>

---

What is this?

Nightscout MCP is a Model Context Protocol server that bridges your Nightscout CGM instance with AI assistants. Ask questions about your glucose data in natural language — the AI gets structured access to your readings, treatments, profiles, statistics, and pattern analysis.

"What's my TIR for the past week?" "How did that pizza affect my glucose?" "Detect patterns in my overnight readings" "Compare training days vs rest days"

Works with any MCP-compatible client.

---

⚡ Quick Start

# 1. Clone and install
git clone https://github.com/adminpb/Nightscout-MCP.git
cd Nightscout-MCP
npm install

# 2. Build
npm run build

# 3. Configure your MCP client (see below)

MCP Client Configuration

Add to your MCP client config (e.g. claude_desktop_config.json):

{
  "mcpServers": {
    "nightscout": {
      "command": "node",
      "args": ["C:\\Magic\\Nightscout-MCP\\dist\\index.js"],
      "env": {
        "NIGHTSCOUT_URL": "https://your-nightscout.example.com",
        "NIGHTSCOUT_TOKEN": "your-read-token",
        "NIGHTSCOUT_UNITS": "mmol/L",
        "NIGHTSCOUT_LOCALE": "en"
      }
    }
  }
}

---

🔧 Tools

Reading Data

| Tool | Description | |:-----|:------------| | get_current_glucose | Latest glucose with trend arrow ↗, delta, age, and status | | get_glucose_history | SGV entries for any time period — hours lookback or exact date range | | get_treatments | Insulin boluses, carb entries, notes, exercise — with summaries | | get_profile | Active profile: ISF, ICR, basal rates, target ranges, DIA | | get_device_status | Pump/sensor/loop status, IOB, COB, battery, predictions | | glucose_at_time | Glucose at a specific moment: "what was my BG at 3 AM?" | | find_events | Search treatments/notes by text or type: "when did I change my sensor?" |

Analytics

| Tool | Description | |:-----|:------------| | get_statistics | TIR, average glucose, estimated HbA1c, GMI, SD, CV, time-in-ranges | | get_daily_report | Full day summary: glucose stats + treatments + notable events | | detect_patterns | Automatic pattern recognition: overnight lows, dawn phenomenon, post-meal spikes, variability | | compare_periods | Side-by-side comparison of two periods: training vs rest, this week vs last | | analyze_meal | Automatic post-meal analysis: peak, time-to-peak, rise, recovery, bolus assessment | | overnight_analysis | Detailed overnight report: stability, drift, dawn phenomenon, basal adequacy | | a1c_estimator | Project future HbA1c based on CGM trends and optional last lab result | | weekly_comparison | One-call this week vs last week with improvement indicators | | insulin_sensitivity_check | Real-world ISF analysis from correction boluses vs profile | | carb_ratio_check | Real-world ICR analysis from meal boluses vs profile | | compression_low_analysis | Detect false lows from sensor compression during sleep | | export_csv | Export glucose + treatments as CSV for doctors or spreadsheets |

Writing Data

| Tool | Description | |:-----|:------------| | add_treatment | Add insulin, carbs, exercise, site change, or any treatment entry | | add_note | Quick timestamped note — meals, symptoms, activities |

Write tools require NIGHTSCOUT_READONLY=false.

📋 Prompts

Pre-built prompt templates for common workflows:

| Prompt | What it does | |:-------|:-------------| | daily_review | Comprehensive analysis of today's glucose patterns | | meal_analysis | Post-meal glucose response assessment | | weekly_summary | 7-day report with TIR trends and recommendations | | optimization_advice | Data-driven suggestions for basal/ISF/ICR adjustments |

📦 Resources

| URI | Description | |:----|:------------| | nightscout://status | Server status, API permissions, version | | nightscout://profile/current | Full active profile as context |

---

⚙️ Configuration

| Variable | Required | Default | Description | |:---------|:--------:|:-------:|:------------| | NIGHTSCOUT_URL | ✅ | — | Your Nightscout instance URL | | NIGHTSCOUT_TOKEN | ✅ | — | Read token (recommended) | | NIGHTSCOUT_API_SECRET | ✅ | — | Or API secret (hashed automatically) | | NIGHTSCOUT_UNITS | | mmol/L | Glucose units: mmol/L or mg/dL | | NIGHTSCOUT_READONLY | | true | Set false to enable write operations | | NIGHTSCOUT_LOCALE | | en | Language: en, uk |

\* Either NIGHTSCOUT_TOKEN or NIGHTSCOUT_API_SECRET is required.

---

🌍 Localization

Nightscout MCP supports multiple languages. All tool names and MCP interface remain in English for compatibility. Locale affects status labels, messages, and report strings in tool responses.

| Locale | Language | |:------:|:---------| | en | English (default) | | uk | Українська (Ukrainian) |

Adding a new locale: create a translation object in src/i18n/index.ts following the TranslationStrings interface. PRs welcome!

---

🔒 Security

Tokens never reach the AI — only processed data is returned via MCP
Read-only by default — write operations require explicit opt-in
Input validation — all parameters validated with Zod schemas
SHA1 hashing — API secrets are hashed before transmission

---

🛠 Development

npm run dev      # TypeScript watch mode
npm run build    # Production build
npm start        # Run the server

Project Structure

src/
├── index.ts              # MCP server — tools, resources, prompts
├── config.ts             # Environment variable configuration
├── client.ts             # Nightscout REST API v1 client
├── i18n/
│   └── index.ts          # Internationalization (en, uk)
└── tools/
    ├── get_current_glucose.ts
    ├── get_glucose_history.ts
    ├── get_statistics.ts
    ├── get_treatments.ts
    ├── get_profile.ts
    ├── get_device_status.ts
    ├── get_daily_report.ts
    ├── detect_patterns.ts
    ├── compare_periods.ts
    ├── analyze_meal.ts
    ├── overnight_analysis.ts
    ├── find_events.ts
    ├── glucose_at_time.ts
    ├── a1c_estimator.ts
    ├── export_csv.ts
    ├── weekly_comparison.ts
    ├── insulin_sensitivity_check.ts
    ├── carb_ratio_check.ts
    ├── compression_low_analysis.ts
    ├── add_treatment.ts
    └── add_note.ts

---

📊 Example Queries

Once connected, you can ask your AI assistant:

"What's my glucose right now?"
"Show my TIR for the past 7 days"
"Analyze how coffee with kefir spiked my glucose"
"Give me a daily report for yesterday"
"What were my lows this week?"
"Do I have a dawn phenomenon?"
"Detect patterns in my last 14 days"
"Compare my glucose on workout days vs rest days"
"Are my basal rates set correctly based on overnight patterns?"
"Is my ISF accurate? Check correction bolus data"
"Am I bolusing enough for meals? Check my carb ratios"
"How am I doing this week compared to last?"
"Are my nighttime lows real or compression artifacts?"
"Estimate my HbA1c for my lab appointment on March 16"
"Export my last 2 weeks as CSV for my doctor"
"Log 45g carbs and 4U insulin for lunch"

---

Roadmap

[x] Core tools: glucose, treatments, statistics, profiles, device status
[x] Daily reports with notable events
[x] Localization (EN / UK)
[x] detect_patterns — overnight lows, dawn phenomenon, post-meal spikes, variability
[x] add_treatment / add_note — write operations
[x] compare_periods — side-by-side period comparison
[x] analyze_meal / overnight_analysis — deep analytics
[x] find_events / glucose_at_time — search and lookup
[x] a1c_estimator — future HbA1c projection
[x] export_csv — data export for doctors
[x] API response caching with TTL
[x] weekly_comparison — auto this-week vs last-week
[x] insulin_sensitivity_check — real ISF from correction data
[x] carb_ratio_check — real ICR from meal data
[x] compression_low_analysis — false low detection
[ ] npm package publishing
[ ] Docker image
[ ] More locales (ES, DE, PL, ...)

---

📄 License

GPL v3 with additional terms under Section 7:

Attribution required — original author adminpb \<adminpb@ukr.net\> must be credited in all copies and derivatives
🇷🇺 Russia restriction — use of this software within the Russian Federation, by RF citizens, or by RF-registered entities is expressly prohibited

Free and open source for everyone else. See LICENSE for full details.

---

<details> <summary><h2>🇺🇦 Українською</h2></summary>

Що це?

Nightscout MCP — це сервер Model Context Protocol, який з'єднує ваш Nightscout з AI-асистентами. Запитуйте про глюкозу природною мовою — AI отримує структурований доступ до показників, лікування, профілів, статистики та аналізу патернів.

«Який у мене TIR за останній тиждень?» «Як піца вплинула на глюкозу?» «Знайди патерни в нічних показниках» «Порівняй дні з тренуванням і без»

Швидкий старт

git clone https://github.com/adminpb/Nightscout-MCP.git
cd Nightscout-MCP
npm install
npm run build

Додайте в конфігурацію вашого MCP-клієнта:

{
  "mcpServers": {
    "nightscout": {
      "command": "node",
      "args": ["C:\\Magic\\Nightscout-MCP\\dist\\index.js"],
      "env": {
        "NIGHTSCOUT_URL": "https://ваш-nightscout.example.com",
        "NIGHTSCOUT_TOKEN": "ваш-токен",
        "NIGHTSCOUT_UNITS": "mmol/L",
        "NIGHTSCOUT_LOCALE": "uk"
      }
    }
  }
}

Інструменти

Читання даних

| Інструмент | Опис | |:-----------|:-----| | get_current_glucose | Поточна глюкоза + тренд ↗, дельта, вік показника | | get_glucose_history | Історія SGV за будь-який період | | get_treatments | Болюси, вуглеводи, нотатки, вправи | | get_profile | Профіль: ISF, ICR, базальні рати, цільові діапазони | | get_device_status | Помпа, сенсор, IOB, COB, батарея | | glucose_at_time | Глюкоза в конкретний момент: «яка була о 3 ночі?» | | find_events | Пошук по записах: «коли міняв сенсор?», «знайди всі записи про каву» |

Аналітика

| Інструмент | Опис | |:-----------|:-----| | get_statistics | TIR, середня, HbA1c, GMI, SD, CV, час у діапазонах | | get_daily_report | Повний звіт за день | | detect_patterns | Патерни: нічні гіпо, феномен світанку, постпрандіальні піки, варіабельність | | compare_periods | Порівняння двох періодів: тренування vs відпочинок, цей тиждень vs минулий | | analyze_meal | Аналіз після їжі: пік, час до піку, підйом, відновлення, оцінка болюсу | | overnight_analysis | Нічний звіт: стабільність, дрейф, феномен світанку, оцінка базалу | | a1c_estimator | Прогноз HbA1c на дату аналізу на основі CGM трендів | | weekly_comparison | Цей тиждень vs минулий з індикаторами покращення | | insulin_sensitivity_check | Реальна ISF з корекційних болюсів vs профіль | | carb_ratio_check | Реальний ICR з їжі vs профіль | | compression_low_analysis | Виявлення хибних лоу від компресії сенсора під час сну | | export_csv | Експорт глюкози + лікування в CSV для лікаря або Excel |

Запис даних

| Інструмент | Опис | |:-----------|:-----| | add_treatment | Додати інсулін, вуглеводи, вправу, заміну катетера | | add_note | Швидка нотатка з відміткою часу |

Запис потребує NIGHTSCOUT_READONLY=false.

Шаблони запитів (Prompts)

| Шаблон | Що робить | |:-------|:----------| | daily_review | Аналіз глюкози за сьогодні | | meal_analysis | Вплив їжі на глюкозу | | weekly_summary | Тижневий звіт з трендами | | optimization_advice | Рекомендації по налаштуваннях |

Змінні середовища

| Змінна | Обов'язкова | Опис | |:-------|:----------:|:-----| | NIGHTSCOUT_URL | ✅ | URL Nightscout інстансу | | NIGHTSCOUT_TOKEN | ✅ | Токен доступу (рекомендовано) | | NIGHTSCOUT_API_SECRET | ✅ | Або API secret | | NIGHTSCOUT_UNITS | | mmol/L або mg/dL | | NIGHTSCOUT_READONLY | | true (за замовч.) або false | | NIGHTSCOUT_LOCALE | | en (за замовч.) або uk |

Безпека

Токени ніколи не передаються в AI — тільки оброблені дані
Read-only за замовчуванням — запис вимагає явного увімкнення
Валідація входу — Zod-схеми для всіх параметрів

Локалізація

Встановіть NIGHTSCOUT_LOCALE=uk для українських статусів та повідомлень. Назви інструментів залишаються англійською для сумісності.

Хочете додати свою мову? Створіть об'єкт перекладу в src/i18n/index.ts за інтерфейсом TranslationStrings.

Ліцензія

GPL v3 з додатковими умовами (Секція 7):

Обов'язкове зазначення автора — оригінальний автор adminpb \<adminpb@ukr.net\> має бути вказаний у всіх копіях та похідних роботах
🇷🇺 Обмеження для РФ — використання цього ПЗ на території Російської Федерації, громадянами РФ або юридичними особами, зареєстрованими в РФ, суворо заборонено

Безкоштовний відкритий код для всіх інших. Деталі в LICENSE.

</details>

---

<p align="center"> 🇺🇦 Made in Ukraine for the civilized world.<br/> <sub>Orcs don't qualify as civilized. Deal with it. 🧌🚫</sub> </p>

Nightscout MCP Server