L1AD/claude-reminders-mcp

Claude Reminders MCP 🔔

Never miss a beat - intelligent reminders that surface automatically in your Claude conversations

What is this?

Claude Reminders MCP is a Model Context Protocol server that manages reminders with a twist: due reminders automatically appear in Claude Code's context via a hook that runs on every message. No need to ask "what's on my list?" - Claude sees what needs attention and proactively brings it up.

Perfect for:

• 🧪 Experiment tracking - "Remind me to check the A/B test results in 3 days"
• 🔄 Follow-ups - "Remind me tomorrow to review the PR feedback"
• 📊 Recurring checks - "Remind me weekly to check our analytics dashboard"
• 🤝 Meeting prep - "Remind me 1 hour before the investor meeting"
• 📦 Dependency updates - "Remind me next month to update our npm packages"

Key Features

🎯 Automatic Surfacing

Due reminders automatically inject into Claude Code's context via a user-prompt-submit hook. Claude sees them before every message without explicit checking.

🗣️ Natural Language

Set reminders using natural language: "tomorrow at 2pm", "in 3 days", "next Monday at 9am", "in 2 weeks"

🎨 Rich Context

Attach structured context (JSON) to reminders for experiments, tools, metrics, etc.

💾 Local & Private

All data stored locally in SQLite (~/.claude-reminders/reminders.db). No cloud services, no tracking.

🔧 Full CRUD Operations

Create, read, update, delete, complete, snooze, and list reminders with ease.

Installation

Prerequisites

• Node.js 18+ and npm
• Claude Code CLI

Quick Start

1. Install and build:

cd claude-reminders-mcp
npm install
npm run build

2. Configure the MCP server:

Open ~/.claude.json (in your home directory) and add or update the mcpServers section:

{
  "mcpServers": {
    "reminders": {
      "command": "node",
      "args": ["/absolute/path/to/claude-reminders-mcp/dist/index.js"]
    }
  }
}

Important:

• Replace /absolute/path/to/ with the actual path where you cloned this repo
• If the file doesn't exist, create it with the above content
• If you already have other MCP servers configured, add the reminders entry alongside them

3. Install the automatic reminder hook:

Due to a Claude Code bug where UserPromptSubmit hooks don't work from subdirectories (Issue #8810), the hook must be installed at the project level:

# Navigate to your project directory
cd /your/project/directory

# Run the hook installer
node /path/to/claude-reminders-mcp/scripts/install-hook.js

This creates a .claude/settings.json file in your project with the hook configuration.

Important: You'll need to run the installer in each project where you want reminders to appear. The MCP server (tools) works globally, but the hook (auto-surfacing) is project-specific due to this Claude Code limitation.

4. Restart Claude Code

That's it! Claude can now manage reminders and will see due ones automatically when you're in this project.

For manual setup or troubleshooting, see

Usage Examples

Setting Reminders

You: Remind me to check the PostHog experiment results in 3 days

Claude: I'll create that reminder for you.
[Uses set_reminder tool]
✅ Reminder created successfully!
ID: 1
Title: Check PostHog experiment results
Due: Saturday 16 Oct 2025 at 14:30
Priority: NORMAL

With Rich Context

You: Remind me tomorrow to check if the paid_landing_test experiment has reached significance

Claude: [Uses set_reminder with context]
{
  "experiment_id": "paid_landing_test",
  "tool": "posthog",
  "metric": "conversion_rate"
}

Automatic Surfacing

When the reminder is due, Claude sees it automatically via the hook:

You: Hello

Claude: Hello! I notice you have a due reminder:

🔴 HIGH: Check PostHog paid_landing_test experiment
- Due: Today at 14:30 (2 hours overdue)
- Context: experiment_id: paid_landing_test

Would you like me to help you check the experiment results now?

How it works: Every time you send a message, a hook runs that injects due reminders into Claude's context. Claude sees them without explicit checking.

Completing Reminders

You: Mark reminder 1 as complete

Claude: [Uses complete_reminder]
✅ Reminder #1 marked as completed!
Check PostHog experiment results
Completed at: 16 Oct 2025, 14:45

Snoozing

You: Snooze that reminder for 2 hours

Claude: [Uses snooze_reminder]
💤 Reminder #1 snoozed!
Will remind you: Today at 16:45

MCP Tools

The server provides 7 tools:

Automatic Surfacing: How It Works

Hook-Based Injection

Instead of relying on MCP resources (which require explicit checking), we use a Claude Code hook that:

1. Runs on every user-prompt-submit event
2. Queries the database for due reminders (<1ms)
3. Injects formatted markdown into Claude's context
4. Stays silent if no reminders are due

Result: Claude genuinely sees your due reminders without you asking.

MCP Resources (Optional)

The server also exposes 3 resources for manual checking:

Note: The hook approach is more reliable than resources for automatic surfacing.

Architecture

┌────────────────────────────────────────────────────┐
│                Claude Code Session                  │
│                                                      │
│  User types message → Hook runs                    │
│                      ↓                              │
│         ┌────────────────────────┐                 │
│         │  check-reminders.js    │                 │
│         │  (reads DB directly)   │                 │
│         └────────┬───────────────┘                 │
│                  │                                  │
│                  ↓                                  │
│         Due reminders injected                     │
│         into context automatically                 │
│                                                     │
│  Claude sees: [Your message] + [Due Reminders]    │
└────────────────────────────────────────────────────┘
                         │
        MCP Tools for management
                         ↓
          ┌──────────────────────────┐
          │  MCP Server (stdio)      │
          │  - set_reminder          │
          │  - complete_reminder     │
          │  - list_reminders        │
          │  - etc.                  │
          └──────────┬───────────────┘
                     │
                     ↓
          ┌──────────────────────────┐
          │  SQLite Database         │
          │  ~/.claude-reminders/    │
          │     reminders.db         │
          └──────────────────────────┘

Key Innovation: Hook-based auto-injection (<1ms) is faster and more reliable than MCP resource polling.

Tech Stack

• Runtime: Node.js 18+ with TypeScript
• MCP SDK: @modelcontextprotocol/sdk v1.0+
• Database: SQLite via better-sqlite3
• Date Parsing: chrono-node for natural language dates
• Storage Location: ~/.claude-reminders/reminders.db

Configuration

Environment Variables

Example:

{
  "mcpServers": {
    "reminders": {
      "command": "node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "REMINDERS_DB_PATH": "/custom/path/reminders.db"
      }
    }
  }
}

Database Schema

CREATE TABLE reminders (
  id INTEGER PRIMARY KEY AUTOINCREMENT,
  title TEXT NOT NULL,
  description TEXT,
  due_date TEXT NOT NULL,               -- ISO 8601 datetime
  priority TEXT NOT NULL DEFAULT 'normal',  -- 'high', 'normal', 'low'
  category TEXT,
  status TEXT NOT NULL DEFAULT 'pending',   -- 'pending', 'completed', 'snoozed'
  context TEXT,                         -- JSON for additional metadata
  snoozed_until TEXT,                   -- ISO 8601 datetime
  created_at TEXT NOT NULL DEFAULT (datetime('now')),
  completed_at TEXT
);

Development

Setup

git clone https://github.com/yourusername/claude-reminders-mcp.git
cd claude-reminders-mcp
npm install

Build

npm run build

Watch mode

npm run dev

Testing

npm test

Roadmap

Phase 1: Core MVP ✅

• SQLite storage
• CRUD operations
• Natural language date parsing
• MCP tools & resources
• Automatic due reminder surfacing

Phase 2: Enhanced Features

• Recurring reminders (daily, weekly, monthly)
• Reminder templates
• Import/export functionality
• CLI for direct database management

Phase 3: Advanced Features

• Optional push notifications
• Integration with calendar apps
• Web dashboard for reminder management
• Collaborative reminders (shared lists)

Phase 4: Ecosystem Integration

• PostHog experiment tracking integration
• GitHub PR/issue reminders
• Linear ticket follow-ups
• Google Analytics scheduled checks

Use Cases

1. Experiment Monitoring

"Remind me in 5 days to check if the homepage_redesign_v2 experiment 
has reached statistical significance in PostHog"

Context: { experiment_id: "homepage_redesign_v2", tool: "posthog" }

2. Code Review Follow-ups

"Remind me tomorrow to follow up on the authentication PR feedback"

Context: { pr_number: 1234, repo: "myapp" }

3. Recurring Health Checks

"Remind me every Monday at 10am to review our error tracking dashboard"

[Recurring reminder - Phase 2 feature]

4. Meeting Preparation

"Remind me 1 hour before the investor meeting with detailed notes"

Context: { meeting_type: "investor", calendar_event_id: "xyz" }

Comparison with Existing Solutions

Contributing

Contributions are welcome! Please see for guidelines.

Areas for Contribution

• Additional date parsing patterns
• New integrations (PostHog, GitHub, etc.)
• UI improvements for resource display
• Performance optimisations
• Bug fixes and tests

Security & Privacy

• 100% Local: All data stored in local SQLite database
• No Network Calls: Server never makes external requests
• No Telemetry: Zero tracking or analytics
• Encrypted at Rest: Use system-level encryption (FileVault, BitLocker)

License

MIT License - see file for details.

Contact & Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Author: Liad

Acknowledgements

Built with:

• Model Context Protocol SDK
• better-sqlite3
• chrono-node

Inspired by the need for better experiment tracking at Wollit.

Made with ❤️ for the Claude community