Reminder MCP Server

Reminder MCP Server

An MCP (Model Context Protocol) server that gives AI assistants reliable reminders, persistent memory, task tracking, and activity history. Built for Poke (an iMessage AI bot) and compatible with any MCP client.

Description

Poke is a great AI assistant, but its built-in reminders, tasks, and memory features had reliability issues. Rather than wait for fixes, I built this MCP server with the help of Claude Code to handle those capabilities myself. The result is a self-hosted stack that makes Poke (and any MCP-compatible client) significantly more useful.

The server exposes 20 MCP tools over Streamable HTTP, backed by a multi-user web dashboard for managing everything through a browser. It supports SQLite for simple setups and PostgreSQL for production, with optional Authentik SSO integration.

Features

• Scheduled Reminders — Time-based notifications with natural language parsing ("tomorrow at 2pm", "in 30 minutes"). Webhook push notifications when reminders trigger.
• Persistent Memory — Store and recall information on demand. Tag-based organization with full-text search and optional semantic search (OpenAI embeddings + Redis). Supports scoped memories (personal, team, application, global) with dedup-on-write and explicit supersedes for session summary chains. Chat-scoped memories allow associating memories with conversation threads for context isolation (accepts any string ID format — UUIDs, CUIDs, etc.).
• Task Tracking — Long-running tasks with configurable check-in intervals (default 5 min). Periodic webhook notifications until completion.
• Activity History — Full audit log of all events. Query by time range, type, and action with day/week/month summaries.
• Web Dashboard — React frontend with stat cards, 30-day activity charts (Recharts), calendar view for reminders, and searchable memory list.
• Teams & Applications — Create teams, add members, and share memories across team members. Applications can be scoped to teams for per-agent knowledge.
• Multi-User — Per-user data isolation with scoped sharing. MCP clients authenticate via API keys (user or team-scoped), the web frontend uses JWT cookies. First user is auto-promoted to admin.
• SSO Integration — Optional Authentik forward auth via Traefik. Users are auto-created on first SSO login.
• API Key Management — Create and revoke API keys from the web UI. Keys are SHA-256 hashed (never stored in plaintext).
• Admin Panel — User management with admin role toggle. Full database backup (.json.gz download) and restore.
• Dark Mode — System preference detection with manual light/dark/system toggle.
• Dual Database Support — SQLite for development and simple deployments, PostgreSQL for production.
• Webhook Notifications — Push notifications to Poke (or any endpoint) when reminders trigger or tasks need check-ins. Supports dynamic webhook registration via MCP tools for programmatic consumers (auto-unregisters after consecutive failures).

Why This Project Is Useful

• Poke's built-in features are unreliable — Reminders don't always fire, memory is inconsistent, and task tracking is limited. This server replaces all of that with a robust, self-hosted alternative.
• Works with any MCP client — Not locked into Poke. Works with Claude Desktop, any MCP-compatible tool, or the included web dashboard.
• You own your data — Self-hosted with full backup/restore. No vendor lock-in, no third-party data storage.
• Multi-user ready — Supports multiple users with data isolation, SSO, and admin controls. Run it for yourself or share it with others.
• Production-grade — PostgreSQL, Docker, health checks, Traefik integration, and Authentik SSO. Not a toy — this runs in production.

MCP Tools (20)

| Tool | Description | |------|-------------| | create_reminder | Schedule a reminder (supports natural language times) | | list_reminders | List pending or all reminders | | complete_reminder | Mark a reminder as completed | | cancel_reminder | Cancel a pending reminder | | remember | Store a memory with optional scope, classification, tags, chat_id, and supersedes | | recall | Retrieve memories across scopes with search/tag/scope/chat_id filter | | forget | Remove a memory (scope-based permission check) | | promote_memory | Copy a memory to a different scope (e.g., personal to team) | | list_scopes | List available memory scopes (personal, teams, apps, global) | | start_task | Begin tracking a long-running task | | check_task | Get status of a specific task | | list_tasks | List tasks with optional status filter | | complete_task | Mark a task as completed | | update_task | Update task status or add notes | | register_webhook | Register a URL to receive push notifications (with optional API key and event filter) | | unregister_webhook | Remove a registered webhook URL | | list_webhooks | List all registered webhooks for this user | | get_pending_checkups | Get all due reminders and tasks needing check-in | | get_activity | Query activity history by time range | | get_summary | Get summary of recent activity |

Getting Started

Option 1: Standalone with SQLite

The simplest setup — no external database required.

# Clone and build
git clone https://github.com/sj7trunks/reminder-mcp.git
cd reminder-mcp
npm install
npm run build

# Generate secrets
export API_KEY=$(openssl rand -hex 32)
export SECRET_KEY=$(openssl rand -hex 32)

# Run in HTTP mode
API_KEY=$API_KEY SECRET_KEY=$SECRET_KEY npm run start:http

# Verify
curl http://localhost:3000/health

The SQLite database is created automatically at ./data/reminder.db.

For local use with Claude Desktop (stdio mode), add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "reminder": {
      "command": "node",
      "args": ["/path/to/reminder-mcp/dist/index.js"],
      "env": {
        "DATABASE_PATH": "/path/to/reminder-mcp/data/reminder.db",
        "DEFAULT_TIMEZONE": "America/Los_Angeles"
      }
    }
  }
}

Option 2: Production with PostgreSQL & Docker

# Generate secrets
export API_KEY=$(openssl rand -hex 32)
export SECRET_KEY=$(openssl rand -hex 32)
export PG_PASSWORD=$(openssl rand -hex 16)

echo "Save these values:"
echo "  API_KEY=$API_KEY"
echo "  SECRET_KEY=$SECRET_KEY"
echo "  PG_PASSWORD=$PG_PASSWORD"

Add to your docker-compose.yml:

services:
  reminder-mcp-postgres:
    image: postgres:16-alpine
    container_name: reminder-mcp-postgres
    restart: unless-stopped
    environment:
      - POSTGRES_USER=reminder
      - POSTGRES_PASSWORD=${PG_PASSWORD}
      - POSTGRES_DB=reminder_mcp
    volumes:
      - reminder-mcp-pg-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U reminder -d reminder_mcp"]
      interval: 10s
      timeout: 5s
      retries: 5
      start_period: 10s

  reminder-mcp:
    build:
      context: ./reminder-mcp
      dockerfile: Dockerfile
    container_name: reminder-mcp
    restart: unless-stopped
    environment:
      - NODE_ENV=production
      - PORT=3000
      - HOST=0.0.0.0
      - API_KEY=${API_KEY}
      - SECRET_KEY=${SECRET_KEY}
      - DATABASE_TYPE=postgres
      - DATABASE_URL=postgresql://reminder:${PG_PASSWORD}@reminder-mcp-postgres:5432/reminder_mcp
      - DEFAULT_TIMEZONE=America/Los_Angeles
      # Optional: Push notifications
      # - WEBHOOK_URL=https://poke.com/api/v1/inbound-sms/webhook
      # - WEBHOOK_API_KEY=your-poke-api-key
      # Optional: Authentik SSO
      # - AUTHENTIK_HOST=https://your-authentik-domain.com
    depends_on:
      reminder-mcp-postgres:
        condition: service_healthy
    ports:
      - "3000:3000"
    healthcheck:
      test: ["CMD", "wget", "--no-verbose", "--tries=1", "--spider", "http://127.0.0.1:3000/health"]
      interval: 30s
      timeout: 3s
      retries: 3
      start_period: 10s

volumes:
  reminder-mcp-pg-data:
    driver: local

docker compose up -d
curl http://localhost:3000/health

Configuring Poke

1. Open Poke > Settings > Integrations > New Integration
2. Fill in:

• Name: Reminders
• Server URL: https://your-domain.com/mcp
• API Key: Your generated API key

1. Create the integration

For push notifications (so Poke messages you when reminders trigger):

1. Go to Poke > Settings > Advanced and generate a webhook API key
2. Set WEBHOOK_URL and WEBHOOK_API_KEY in your environment

Important: Poke requires SSE (Server-Sent Events) format. Configure your MCP client to accept text/event-stream in addition to application/json.

Optional: Semantic Search

Enable AI-powered semantic search for memories using OpenAI embeddings and Redis:

# Set environment variables
export OPENAI_API_KEY=sk-...
export REDIS_URL=redis://localhost:6379

# Or add to docker-compose.yml
environment:
  - OPENAI_API_KEY=${OPENAI_API_KEY}
  - REDIS_URL=redis://redis:6379

Semantic search uses text-embedding-3-small (1536 dimensions) stored in Redis with vector similarity search. Embeddings are generated automatically in the background when memories are created or updated.

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | API_KEY | Yes (HTTP) | - | Seed API key (hashed on first run) | | SECRET_KEY | Yes | - | JWT signing secret | | PORT | No | 3000 | HTTP server port | | HOST | No | 0.0.0.0 | HTTP server bind address | | DATABASE_TYPE | No | sqlite | sqlite or postgres | | DATABASE_PATH | No | ./data/reminder.db | SQLite file path | | DATABASE_URL | No | - | PostgreSQL connection string | | DEFAULT_TIMEZONE | No | America/Los_Angeles | Default timezone | | WEBHOOK_URL | No | - | Push notification endpoint | | WEBHOOK_API_KEY | No | - | Bearer token for webhook | | AUTHENTIK_HOST | No | - | Authentik base URL for SSO | | OPENAI_API_KEY | No | - | OpenAI API key for semantic search | | REDIS_URL | No | - | Redis URL for vector storage (semantic search) | | LOG_LEVEL | No | info | debug, info, warn, error |

Project Structure

reminder-mcp/
├── src/
│   ├── index.ts              # stdio transport entry point
│   ├── http.ts               # HTTP transport entry point (Express app)
│   ├── server.ts             # MCP server & tool registration
│   ├── config/
│   │   └── index.ts          # Zod-validated environment config
│   ├── types/
│   │   └── context.ts        # McpContext interface for scope/auth
│   ├── db/
│   │   ├── index.ts          # Knex connection (SQLite/PostgreSQL)
│   │   ├── migrations/       # Database migrations (001-013)
│   │   └── models/           # Zod schemas (User, ApiKey, Team, Memory, etc.)
│   ├── middleware/
│   │   └── auth.ts           # JWT, API key, Authentik SSO middleware
│   ├── routes/
│   │   ├── auth.ts           # Register, login, logout, session
│   │   ├── keys.ts           # API key management
│   │   ├── reminders.ts      # Reminder CRUD
│   │   ├── memories.ts       # Memory CRUD with search + scope filtering
│   │   ├── tasks.ts          # Task CRUD
│   │   ├── stats.ts          # Dashboard statistics
│   │   ├── admin.ts          # User management, backup/restore
│   │   ├── teams.ts          # Team CRUD + member management
│   │   └── applications.ts   # Application CRUD
│   ├── services/
│   │   ├── scheduler.ts      # Background job scheduler (60s poll)
│   │   ├── notifier.ts       # Webhook notifications (Poke format)
│   │   ├── timezone.ts       # Timezone conversion & parsing
│   │   ├── embedding.ts      # OpenAI embeddings (text-embedding-3-small)
│   │   └── embedding-worker.ts  # Background worker for generating embeddings
│   ├── tools/
│   │   ├── reminders.ts      # Reminder MCP tools
│   │   ├── memory.ts         # Memory MCP tools
│   │   ├── tasks.ts          # Task MCP tools
│   │   └── history.ts        # Activity query tools
│   └── resources/
│       └── status.ts         # Server status resource
├── frontend/
│   ├── src/
│   │   ├── main.tsx          # React entry point
│   │   ├── App.tsx           # Router with auth guards
│   │   ├── api/client.ts     # API client (fetch + credentials)
│   │   ├── components/
│   │   │   └── Layout.tsx    # App shell with nav & theme toggle
│   │   ├── contexts/
│   │   │   └── ThemeContext.tsx  # Dark/light/system theme
│   │   └── pages/
│   │       ├── Login.tsx     # Login form + SSO button
│   │       ├── Register.tsx  # Registration form
│   │       ├── Dashboard.tsx # Stats + activity chart
│   │       ├── Reminders.tsx # Calendar view
│   │       ├── Memories.tsx  # Searchable memory list with scope filter
│   │       ├── Teams.tsx     # Team management + members
│   │       ├── Settings.tsx  # API keys (user/team) + theme
│   │       └── Admin.tsx     # User mgmt + backup/restore
│   ├── vite.config.ts        # Vite config with dev proxy
│   └── tailwind.config.js    # Tailwind CSS config
├── Dockerfile                # Multi-stage Docker build
├── docker-compose.yml        # Standalone Docker setup
├── .env.example              # Environment variable template
├── CLAUDE.md                 # Development guide for AI assistants
└── LICENSE                   # MIT License

Tech Stack

• Runtime: Node.js 20 + TypeScript (ESM)
• MCP: @modelcontextprotocol/sdk (Streamable HTTP transport)
• Backend: Express 5, Knex.js, Zod
• Frontend: React 18, Vite, Tailwind CSS, React Query, Recharts
• Database: SQLite (better-sqlite3) or PostgreSQL
• Auth: JWT (jsonwebtoken), bcrypt, SHA-256 API key hashing
• SSO: Authentik forward auth via Traefik

Getting Help

If you encounter issues or have questions:

• Open an Issue — Bug reports and feature requests
• Discussions — Questions and general discussion

Credits

Built by Benjamin Coles with Claude Code.

License

MIT — see LICENSE.

Security Notice

This project was built as a personal tool and has not undergone a formal security audit. If you deploy this in production:

• Generate strong, unique values for API_KEY and SECRET_KEY (openssl rand -hex 32)
• Use HTTPS (TLS) for all traffic — never expose the API over plain HTTP
• Review the authentication middleware (src/middleware/auth.ts) for your threat model
• Keep dependencies updated (npm audit)
• Consider network-level access controls (firewall rules, VPN) in addition to application-level auth
• The admin backup/restore endpoints can export and overwrite all data — restrict admin access carefully