Skip to main content

​
Summary

The Reminders MCP server enables AI assistants to create and manage reminders within conversations. Supports both one-time reminders (scheduled_at) and recurring reminders (cron expressions) with timezone awareness. Requires conversation API key for authentication.

​
Authentication

This server requires a conversation API key. The key is automatically provided when tools are called within an Agentic Loop. 
# Requires conversation API key
curl https://app.chatbotplatform.io/mcp/reminders/call/list-reminders \
  -H "Authorization: Bearer conv_xxxxx..."
Automatic in Agentic Loops: When using this server within an Agentic Loop, the conversation API key is provided automatically - no manual setup required.

​
Use Cases

​
One-Time Meeting Reminder

User: “Remind me about the team meeting tomorrow at 2pm” Tool Calls:
  1. create-reminder with message “Team meeting”, scheduled_at “2026-02-05T14:00:00”, timezone “America/New_York”
Result: Reminder created, will trigger tomorrow at 2pm EST

​
Daily Standup Reminder

User: “Remind me every weekday at 9am about standup” Tool Calls:
  1. create-reminder with message “Daily standup”, cron_expression “0 9 * * 1-5”, timezone “America/Los_Angeles”
Result: Recurring reminder created, triggers Monday-Friday at 9am PST

​
Managing Reminders

User: “What reminders do I have coming up?” Tool Calls:
  1. list-reminders with status “active” → Shows all active reminders
  2. User: “Cancel the one about standup”
  3. delete-reminder with reminder_id from the standup reminder
Result: List of active reminders displayed, standup reminder deleted

​
Available Tools

​
create-reminder

Create a new reminder for the conversation.
ParameterTypeRequiredDescription
messagestringYesWhat to remind the user about
scheduled_atstringNo*For one-time reminders: ISO 8601 datetime (e.g., “2026-12-25T09:00:00”). Interpreted in the specified timezone.
cron_expressionstringNo*For recurring reminders: cron schedule (e.g., “0 9 * * *” for daily at 9am, “0 9 * * 1-5” for weekdays)
timezonestringNoTimezone for the schedule (IANA identifier, default: “UTC”). Examples: “America/New_York”, “Europe/London”, “Asia/Tokyo”
Returns: Confirmation with reminder details including ID, message, schedule, and next run time.
Either/Or Requirement: You must provide either scheduled_at (one-time) or cron_expression (recurring), but not both.
One-Time Reminder Example: 
Input:
  message: "Team meeting"
  scheduled_at: "2026-02-05T14:00:00"
  timezone: "America/New_York"

Output:
  Reminder created successfully
  ID: 550e8400-e29b-41d4-a716-446655440000
  Message: Team meeting
  Type: One-time
  Scheduled for: 2026-02-05 14:00:00 EST
  Status: Active
Recurring Reminder Example: 
Input:
  message: "Daily standup"
  cron_expression: "0 9 * * 1-5"
  timezone: "America/Los_Angeles"

Output:
  Reminder created successfully
  ID: 660e8400-e29b-41d4-a716-446655440000
  Message: Daily standup
  Type: Recurring
  Schedule: 0 9 * * 1-5 (Every weekday at 9:00 AM)
  Next run: 2026-02-05 09:00:00 PST
  Status: Active
Cron Expression Format: 
* * * * *
│ │ │ │ │
│ │ │ │ └─ Day of week (0-7, where 0 and 7 are Sunday)
│ │ │ └─── Month (1-12)
│ │ └───── Day of month (1-31)
│ └─────── Hour (0-23)
└───────── Minute (0-59)
Common Cron Patterns:
  • 0 9 * * * - Every day at 9:00 AM
  • 0 9 * * 1-5 - Every weekday at 9:00 AM
  • 0 */2 * * * - Every 2 hours
  • 30 8 * * 1 - Every Monday at 8:30 AM
  • 0 0 1 * * - First day of every month at midnight

​
list-reminders

List all reminders for the conversation.
ParameterTypeRequiredDescription
statusstringNoFilter by status: “active”, “paused”, “completed”, “failed”
limitintegerNoMaximum reminders to return (1-100, default: 20)
Returns: Table of reminders ordered by next run time (upcoming first) with ID, message, type, next run time, and status. Example: 
Input: status: "active"

Output:
  Active Reminders (ordered by next run time):

  | ID | Message | Type | Next Run | Status |
  |----|---------|------|----------|--------|
  | 550e84... | Team meeting | One-time | 2026-02-05 14:00 EST | active |
  | 660e84... | Daily standup | Recurring | 2026-02-05 09:00 PST | active |
  | 770e84... | Weekly report | Recurring | 2026-02-07 17:00 UTC | active |
Status Filters:
  • active - Currently enabled reminders
  • paused - Temporarily disabled reminders
  • completed - One-time reminders that have triggered
  • failed - Reminders that encountered errors

​
get-reminder

Get full details of a specific reminder by its ID.
ParameterTypeRequiredDescription
reminder_idstringYesThe UUID of the reminder to retrieve
Returns: Complete reminder information including schedule, timezone, and run history. Example: 
Input: reminder_id: "660e8400-e29b-41d4-a716-446655440000"

Output:
  Reminder Details:

  ID: 660e8400-e29b-41d4-a716-446655440000
  Message: Daily standup reminder
  Type: Recurring
  Cron Expression: 0 9 * * 1-5 (Every weekday at 9:00 AM)
  Timezone: America/Los_Angeles (PST, UTC-08:00)
  Status: Active

  Schedule:
  - Next Run: 2026-02-05 09:00:00 PST
  - Last Run: 2026-02-04 09:00:00 PST

  Created: 2026-01-15 10:30:00 UTC
Reminder Not Found: If the reminder_id doesn’t exist for this conversation, an error is returned.

​
update-reminder

Update an existing reminder’s message, schedule, timezone, or status.
ParameterTypeRequiredDescription
reminder_idstringYesThe UUID of the reminder to update
messagestringNoNew reminder message
scheduled_atstringNoNew scheduled time for one-time reminders (ISO 8601 datetime)
cron_expressionstringNoNew cron expression for recurring reminders
timezonestringNoNew timezone for the schedule
statusstringNoNew status: “active” to enable, “paused” to temporarily disable
Returns: Confirmation with updated reminder details.
Partial Updates: You only need to provide the fields you want to change. Other fields remain unchanged.
Example - Pause a Reminder: 
Input:
  reminder_id: "660e8400-e29b-41d4-a716-446655440000"
  status: "paused"

Output:
  Reminder updated successfully
  ID: 660e8400-e29b-41d4-a716-446655440000
  Status changed: active → paused
Example - Change Schedule: 
Input:
  reminder_id: "660e8400-e29b-41d4-a716-446655440000"
  cron_expression: "0 10 * * 1-5"

Output:
  Reminder updated successfully
  Schedule updated: 0 9 * * 1-5 → 0 10 * * 1-5
  Next run: 2026-02-05 10:00:00 PST (recalculated)
Valid Status Transitions:
  • active → paused (temporarily disable)
  • paused → active (re-enable)
Cannot Update Completed or Failed: Only active and paused reminders can be updated. Completed or failed reminders must be deleted and recreated.

​
delete-reminder

Permanently delete a reminder by its ID.
ParameterTypeRequiredDescription
reminder_idstringYesThe UUID of the reminder to delete
Returns: Confirmation with deleted reminder’s ID and message. Example: 
Input: reminder_id: "660e8400-e29b-41d4-a716-446655440000"

Output:
  Reminder deleted successfully
  ID: 660e8400-e29b-41d4-a716-446655440000
  Message: Daily standup reminder
Permanent Action: Deletion cannot be undone. The reminder is permanently removed from the database.

​
Common Workflows

​
Creating a Quick Reminder

1

Parse User Request

Extract message, time, and timezone from user’s natural language request
2

Create One-Time Reminder

Use create-reminder with scheduled_at in ISO 8601 format
3

Confirm

Show confirmation with formatted reminder details

​
Setting Up Recurring Reminders

1

Determine Pattern

Convert user’s request to cron expression (e.g., “every weekday” → “0 9 * * 1-5”)
2

Create Recurring Reminder

Use create-reminder with cron_expression
3

Verify Next Run

Confirm the next run time matches user’s expectation

​
Managing Reminders

1

List Reminders

Use list-reminders to show all active reminders
2

User Selects Action

User identifies which reminder to modify or delete
3

Update or Delete

Use update-reminder to modify or delete-reminder to remove

​
Timezone Best Practices

​
Validating Timezones

Before creating reminders, validate the user’s timezone:
1

Ask for Timezone

“What timezone are you in?”
2

Search Timezones

Use Time Utilities timezones tool to find valid identifiers
3

Confirm

Show the user their timezone with current time using now tool
4

Create Reminder

Use validated timezone identifier with create-reminder

​
Common Timezone Identifiers

RegionTimezone IdentifierOffset
US EasternAmerica/New_YorkUTC-05:00 (EST) / UTC-04:00 (EDT)
US CentralAmerica/ChicagoUTC-06:00 (CST) / UTC-05:00 (CDT)
US MountainAmerica/DenverUTC-07:00 (MST) / UTC-06:00 (MDT)
US PacificAmerica/Los_AngelesUTC-08:00 (PST) / UTC-07:00 (PDT)
UKEurope/LondonUTC+00:00 (GMT) / UTC+01:00 (BST)
Central EuropeEurope/ParisUTC+01:00 (CET) / UTC+02:00 (CEST)
JapanAsia/TokyoUTC+09:00 (JST)
AustraliaAustralia/SydneyUTC+10:00 (AEST) / UTC+11:00 (AEDT)
Daylight Saving Time: IANA timezone identifiers automatically handle DST transitions. Times remain consistent from the user’s perspective.

​
Tips & Best Practices

  • Always specify timezone when creating reminders to avoid confusion (defaults to UTC if not specified)
  • Use ISO 8601 format for scheduled_at (e.g., “2026-02-05T14:00:00”)
  • Test cron expressions before creating - incorrect patterns may not trigger as expected
  • Pause instead of delete if the user might want to re-enable the reminder later
  • List reminders before updating or deleting to confirm you’re acting on the right one
  • Consider user’s intent - “tomorrow at 2pm” should use their local timezone, not UTC

​
Cron Expression Tips

  • Use online tools to validate cron expressions before creating reminders
  • Common mistake: 0 9 1-5 * * (days 1-5 of month) vs 0 9 * * 1-5 (Mon-Fri)
  • Be explicit: 0 9 * * 1,2,3,4,5 is clearer than 0 9 * * 1-5 for some users
  • Test thoroughly: Create a test reminder with short intervals to verify the pattern works

​
Reminder Lifecycle

1

Created

Reminder is created with create-reminder and status is active
2

Pending

Reminder awaits its next_run_at timestamp
3

Triggered

At the scheduled time, a synthetic message is sent to the conversation
4

One-Time: Completed

One-time reminders move to completed status after triggering
5

Recurring: Next Run Calculated

Recurring reminders calculate the next next_run_at based on cron expression
6

Failed (if error)

If the reminder cannot be delivered, status changes to failed

API Reference

View the complete API specification for Reminders MCP server endpoints