> ## Documentation Index
> Fetch the complete documentation index at: https://docs.chatbotplatform.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Reminders MCP Server
> Create, manage, and trigger one-time and recurring reminders for conversations with full timezone support.
## 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.
```bash theme={null}
# 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.
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------- |
| `message` | string | Yes | What to remind the user about |
| `scheduled_at` | string | No\* | For one-time reminders: ISO 8601 datetime (e.g., "2026-12-25T09:00:00"). Interpreted in the specified timezone. |
| `cron_expression` | string | No\* | For recurring reminders: cron schedule (e.g., "0 9 \* \* \*" for daily at 9am, "0 9 \* \* 1-5" for weekdays) |
| `timezone` | string | No | Timezone 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.
| Parameter | Type | Required | Description |
| --------- | ------- | -------- | ----------------------------------------------------------- |
| `status` | string | No | Filter by status: "active", "paused", "completed", "failed" |
| `limit` | integer | No | Maximum 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.
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ------------------------------------ |
| `reminder_id` | string | Yes | The 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.
| Parameter | Type | Required | Description |
| ----------------- | ------ | -------- | --------------------------------------------------------------- |
| `reminder_id` | string | Yes | The UUID of the reminder to update |
| `message` | string | No | New reminder message |
| `scheduled_at` | string | No | New scheduled time for one-time reminders (ISO 8601 datetime) |
| `cron_expression` | string | No | New cron expression for recurring reminders |
| `timezone` | string | No | New timezone for the schedule |
| `status` | string | No | New 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.
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | ---------------------------------- |
| `reminder_id` | string | Yes | The 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
Extract message, time, and timezone from user's natural language request
Use `create-reminder` with `scheduled_at` in ISO 8601 format
Show confirmation with formatted reminder details
### Setting Up Recurring Reminders
Convert user's request to cron expression (e.g., "every weekday" → "0 9 \* \* 1-5")
Use `create-reminder` with `cron_expression`
Confirm the next run time matches user's expectation
### Managing Reminders
Use `list-reminders` to show all active reminders
User identifies which reminder to modify 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:
"What timezone are you in?"
Use Time Utilities `timezones` tool to find valid identifiers
Show the user their timezone with current time using `now` tool
Use validated timezone identifier with `create-reminder`
### Common Timezone Identifiers
| Region | Timezone Identifier | Offset |
| -------------- | -------------------- | ----------------------------------- |
| US Eastern | America/New\_York | UTC-05:00 (EST) / UTC-04:00 (EDT) |
| US Central | America/Chicago | UTC-06:00 (CST) / UTC-05:00 (CDT) |
| US Mountain | America/Denver | UTC-07:00 (MST) / UTC-06:00 (MDT) |
| US Pacific | America/Los\_Angeles | UTC-08:00 (PST) / UTC-07:00 (PDT) |
| UK | Europe/London | UTC+00:00 (GMT) / UTC+01:00 (BST) |
| Central Europe | Europe/Paris | UTC+01:00 (CET) / UTC+02:00 (CEST) |
| Japan | Asia/Tokyo | UTC+09:00 (JST) |
| Australia | Australia/Sydney | UTC+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
Reminder is created with `create-reminder` and status is `active`
Reminder awaits its `next_run_at` timestamp
At the scheduled time, a synthetic message is sent to the conversation
One-time reminders move to `completed` status after triggering
Recurring reminders calculate the next `next_run_at` based on cron expression
If the reminder cannot be delivered, status changes to `failed`
***
View the complete API specification for Reminders MCP server endpoints