CareLoop - Medication Reminder MCP Server

A Python MCP (Model Context Protocol) server for tracking medication doses with automatic alerts, built with the official mcp SDK and SQLite.

Setup

1. Create Virtual Environment (Windows)

cd careloop
python -m venv venv
.\venv\Scripts\Activate.ps1

2. Install Dependencies

pip install "mcp[cli]" requests fastapi uvicorn

3. Run the Server

python server.py

The server starts with:

• MCP Server: stdio transport (for MCP clients like Claude)

• HTTP Server: http://localhost:8000

  • Dashboard: http://localhost:8000/

  • API: http://localhost:8000/api/state

Related MCP server: CareCircle MCP Server

Features

MCP Tools

Access these tools through any MCP-compatible client:

• add_dose(name, due_time) - Schedule a new medication dose

  • name: Medication name (string)

  • due_time: ISO format datetime (e.g., 2024-01-15T09:00:00)

• confirm_dose(name) - Mark a dose as taken

  • name: Medication name to confirm

• whats_next() - Get the next pending dose

  • Returns: Next dose with alert level and minutes until/late

• log_ring_event(kind) - Log user interactions

  • kind: Event type (e.g., button_pressed, snooze, reminder_shown)

HTTP Routes

• GET /api/state - Get JSON state of all doses

  • Includes alert counts (warning/urgent)

  • Flags chronic misses (2+ missed in last 3 days)

  • Real-time minutes late calculation

• GET / - Dark theme dashboard with 3-second polling

  • Large, readable medication list

  • Alert badges (urgent/warning)

  • Chronic miss indicators

  • Auto-updating every 3 seconds

Background Alerting

The server runs a background thread that monitors doses:

• 2 minutes late: Sends warning alert via ntfy.sh (if enabled)

• 5 minutes late: Sends urgent alert via ntfy.sh (if enabled)

Alerts are sent to https://ntfy.sh/<your-topic> (configure via NTFY_TOPIC environment variable).

Configuration

NTFY_TOPIC Environment Variable

The ntfy.sh topic is configured via the NTFY_TOPIC environment variable. This prevents the topic from being exposed in the repository.

Important: ntfy.sh topics are public. Choose a unique, hard-to-guess name to prevent unauthorized users from receiving your alerts.

Setting the topic:

PowerShell (Windows):

$env:NTFY_TOPIC="your-random-topic-12345"
python server.py

macOS/Linux:

export NTFY_TOPIC="your-random-topic-12345"
python server.py

Verify it's set: You should see ntfy topic: your-random-topic-12345 in the server startup output.

Subscribing to alerts:

1. Install the ntfy.sh app (available on iOS and Android)

2. Subscribe to your chosen topic in the app

3. You'll receive notifications when doses are late

Database

Uses SQLite (doses.db) with two tables:

doses (id, name, due_time, confirmed, confirmed_at, created_at)
ring_events (id, kind, dose_id, timestamp)

Medical Disclaimer

⚠️ No Medical Advice: This system is a reminder tool only. It does not provide medical advice and should not replace professional medical guidance. Always consult healthcare providers for medication decisions.

Example Usage

Add a dose via HTTP

# Not directly via HTTP - use MCP tools instead
# Example via MCP client or programmatically

Check state via HTTP

curl http://localhost:8000/api/state

Response:

{
  "doses": [
    {
      "id": 1,
      "name": "Aspirin",
      "due_time": "2024-01-15T14:30:00",
      "confirmed": false,
      "confirmed_at": null,
      "minutes_late": 5.5,
      "alert_level": "urgent",
      "chronic_miss": false
    }
  ],
  "alerts": {
    "warning_count": 0,
    "urgent_count": 1
  },
  "timestamp": "2024-01-15T14:35:32.123456"
}

View Dashboard

Open http://localhost:8000/ in your browser for the dark-themed dashboard.

Integration with MCP Clients

Using with Claude Desktop

1. Create a configuration file at ~/.config/claude-desktop/claude_desktop_config.json:

{
  "mcpServers": {
    "careloop": {
      "command": "python",
      "args": ["/path/to/careloop/server.py"]
    }
  }
}

2. Restart Claude Desktop to connect.

3. Use the CareLoop tools in your conversations with Claude.

Testing

Run the test script:

python test_server.py

Customization

• Alert Topic: Modify send_alert() function to use custom ntfy.sh topic

• Port: Change port 8000 in the main script to use a different port

• Database Path: Set DB_PATH variable to store database elsewhere

• Alert Timing: Adjust 2-minute and 5-minute thresholds in alert_worker()

Architecture

• Backend: Python with mcp SDK, FastAPI, SQLite

• Frontend: Single-page app with vanilla JavaScript

• Transport: stdio for MCP protocol, HTTP for dashboard

• Alerting: Background thread with ntfy.sh integration