Skip to main content
Glama
dbmcco

apple-reminders-mcp

by dbmcco
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

Apple Reminders MCP Server

A Model Context Protocol (MCP) server that provides seamless integration between Claude and macOS Apple Reminders app. Built with TypeScript and AppleScript for reliable, native Reminders access.

Features

  • Complete Reminders Management: Create, read, update, and delete reminders

  • List Management: Access and organize reminders across multiple lists

  • Advanced Filtering: Search by text, filter by completion status, or target specific lists

  • Rich Metadata: Due dates, priorities, notes, creation/modification timestamps

  • Native Integration: Direct AppleScript integration with zero external dependencies

  • Type-Safe: Built with TypeScript for reliability and maintainability

Related MCP server: quick-reminder-mcp

Requirements

  • macOS: This server uses AppleScript and requires macOS with the Reminders app

  • Node.js: Version 16 or higher

  • Claude Desktop or Claude Code CLI: For MCP integration

Installation

From Source

  1. Clone this repository:

git clone https://github.com/dbmcco/apple-reminders-mcp.git
cd apple-reminders-mcp

  1. Install dependencies:

npm install

  1. Build the server:

npm run build

Configuration

For Claude Desktop

Add this to your Claude Desktop configuration file (~/Library/Application Support/Claude/claude_desktop_config.json):

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

For Claude Code CLI

Run this command:

claude mcp add -s user reminders node /absolute/path/to/apple-reminders-mcp/dist/index.js

Important: Replace /absolute/path/to/apple-reminders-mcp with the actual path where you cloned this repository.

Available MCP Tools

list_reminder_lists

Get all available reminder lists.

Returns: Array of lists with name and id properties.

Example:

// Response:
[
  {"name": "Reminders", "id": "x-apple-reminder://..."},
  {"name": "Work", "id": "x-apple-reminder://..."},
  {"name": "Personal", "id": "x-apple-reminder://..."}
]

get_reminders

Retrieve reminders with optional filtering.

Parameters:

  • listName (string, optional): Filter by specific list name

  • completed (boolean, optional): Filter by completion status

  • searchTerm (string, optional): Search in names and bodies

Returns: Array of reminder objects with full metadata.

Examples:

// Get all incomplete reminders
get_reminders(undefined, false)

// Get all reminders from "Work" list
get_reminders("Work")

// Get completed reminders from "Personal" list
get_reminders("Personal", true)

// Search for reminders containing "meeting"
get_reminders(undefined, undefined, "meeting")

create_reminder

Create a new reminder in a specified list.

Parameters:

  • name (string, required): Reminder title

  • listName (string, required): Target list name

  • body (string, optional): Notes/description

  • dueDate (string, optional): Due date in format "MM/DD/YYYY HH:MM AM/PM"

  • priority (number, optional): 0=none, 1=high, 5=medium, 9=low

Returns: ID of the created reminder.

Examples:

// Simple reminder
create_reminder("Buy groceries", "Personal")

// Reminder with due date and priority
create_reminder(
  "Submit report",
  "Work",
  "Include Q4 metrics",
  "12/31/2025 5:00 PM",
  1
)

// Reminder with notes
create_reminder(
  "Call dentist",
  "Personal",
  "Schedule annual checkup"
)

update_reminder

Update an existing reminder.

Parameters:

  • reminderId (string, required): ID of the reminder to update

  • name (string, optional): New title

  • body (string, optional): New notes

  • completed (boolean, optional): Completion status

  • dueDate (string, optional): New due date

  • priority (number, optional): New priority

Examples:

// Mark reminder as complete
update_reminder("x-apple-reminder://...", {completed: true})

// Update due date
update_reminder("x-apple-reminder://...", {
  dueDate: "01/15/2026 2:00 PM"
})

// Update multiple fields
update_reminder("x-apple-reminder://...", {
  name: "Updated title",
  body: "New notes",
  priority: 1
})

delete_reminder

Delete a reminder permanently.

Parameters:

  • reminderId (string, required): ID of the reminder to delete

Example:

delete_reminder("x-apple-reminder://...")

search_reminders

Search for reminders by text in names or bodies.

Parameters:

  • searchTerm (string, required): Text to search for

Returns: Array of matching reminder objects.

Example:

// Find all reminders mentioning "Claude"
search_reminders("Claude")

Usage Examples

Example 1: Daily Task Management

You: Show me all incomplete tasks from my "Today" list
Claude: [uses get_reminders("Today", false)]

You: Mark the first one as complete
Claude: [uses update_reminder with completed: true]

Example 2: Quick Capture

You: Remind me to call John tomorrow at 2pm
Claude: [uses create_reminder with due date]

Example 3: Project Organization

You: Show me all reminders related to the "Website" project
Claude: [uses search_reminders("Website")]

You: Move them all to the "Work" list
Claude: [uses update_reminder for each result]

Example 4: Weekly Review

You: What did I complete this week in my "Personal" list?
Claude: [uses get_reminders("Personal", true)]

Data Model

Reminder Object

{
  id: string;                 // Unique reminder ID
  name: string;               // Reminder title
  body?: string;              // Optional notes/description
  completed: boolean;         // Completion status
  list: string;               // Parent list name
  dueDate?: string;           // Optional due date
  priority: number;           // 0=none, 1=high, 5=medium, 9=low
  creationDate: string;       // When reminder was created
  modificationDate: string;   // When last modified
}

RemindersList Object

{
  name: string;  // List display name
  id: string;    // Unique list ID
}

Development

Build

npm run build

Watch Mode

npm run dev

Run Server Directly

npm run start

Architecture

This MCP server uses a clean architecture:

  1. MCP Server Layer (index.ts): Handles MCP protocol communication

  2. AppleScript Executor (applescript-executor.ts): Manages all Reminders app interactions

  3. Type Safety: Zod validation and TypeScript for reliability

The AppleScript integration uses osascript for direct system integration, avoiding external dependencies and app translocation issues.

Troubleshooting

Permission Issues

If you get permission errors, ensure:

  1. Terminal (or your app) has Automation permissions for Reminders

  2. Go to System Preferences > Security & Privacy > Privacy > Automation

  3. Enable access for the app running this server

Date Format Issues

Due dates must use the format: "MM/DD/YYYY HH:MM AM/PM"

Examples:

  • "12/25/2025 9:00 AM"

  • "01/01/2026 11:30 PM"

Reminder IDs

Reminder IDs are system-generated Apple URLs (e.g., x-apple-reminder://...). They're not portable across systems but are stable within a single macOS installation.

Credits

Built with Claude (Anthropic) using the Model Context Protocol SDK.

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Support

For issues, questions, or feature requests, please open an issue on GitHub.

Available Tools

6 tools
create_reminderB

Create a new reminder in a specified list

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNoOptional body/notes for the reminder
nameYesName of the reminder
dueDateNoOptional due date in format "MM/DD/YYYY HH:MM AM/PM"
listNameYesName of the list to add the reminder to
priorityNoPriority level (0=none, 1=high, 5=medium, 9=low)

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the burden of disclosing behavioral traits, but it only restates the action. It fails to mention side effects, idempotency, requirements such as list existence, or the return value, leaving the agent without critical behavioral context for a mutation operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is front-loaded with the action and resource. It contains no unnecessary words or fluff, earning a perfect score for conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has no annotations or output schema, and the description is minimal. While the schema covers parameter semantics, the description does not explain return values, prerequisites, or error behavior, leaving significant gaps for a create operation. This is insufficient for a complete understanding of how to use the tool effectively.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema provides complete descriptions for all five parameters, achieving 100% coverage. The description adds no additional parameter meaning beyond what the schema already offers, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: creating a new reminder in a specified list. It distinguishes from sibling tools like update_reminder, delete_reminder, and search_reminders by focusing on creation, with the additional context of targeting a specific list.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for creating a new reminder, but provides no explicit guidance on when to choose this tool over alternatives. No exclusions or prerequisites are mentioned, leaving the agent to infer that it should be used for new reminders rather than updates or deletions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

delete_reminderB

Delete a reminder by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
reminderIdYesID of the reminder to delete

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden for behavioral disclosure. It states 'Delete' but does not reveal whether the deletion is permanent or reversible, what happens to dependent data, whether an error occurs for non-existent IDs, or what the response includes. This is a significant gap for a destructive tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, focused sentence. It is concise, front-loaded, and contains no fluff. Every word earns its place given the tool's simplicity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool is simple (1 parameter, no output schema), but the description is minimal. It does not explain what the caller should expect after deletion (e.g., success acknowledgement, deleted object, 404 error). This makes it incomplete for an autonomous agent that needs to infer handling of the operation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% (reminderId is described as 'ID of the reminder to delete'). The tool description adds no further semantic value beyond the schema, so the baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description "Delete a reminder by ID" clearly identifies the action (delete), the resource (reminder), and the method (by ID). It is specific and distinguishes this tool from siblings like create_reminder, update_reminder, and search_reminders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: you would use this tool when you want to delete a specific reminder identified by its ID. However, it provides no explicit when-to-use or when-not-to-use guidance, nor does it mention alternatives like update_reminder or soft-delete behavior.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_remindersB

Get reminders from a specific list or all lists, with optional filtering

ParametersJSON Schema
NameRequiredDescriptionDefault
listNameNoName of the reminder list to search in (optional)
completedNoFilter by completion status (optional)
searchTermNoSearch term to filter reminders by name or body (optional)

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only says 'Get reminders' and mentions filtering, but does not describe return format, pagination, ordering, or any side effects. For a read operation this is a minimal disclosure, but still lacks detail.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the core purpose. No wasted words, and it is appropriately sized for a simple retrieval tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the low complexity and full schema coverage, the description is adequate but has gaps: no output schema is provided, no annotations, and the relationship to search_reminders is unclear. A more complete description would mention when to use this instead of search_reminders and what the response contains.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage for all three parameters, so the baseline is 3. The description adds a small amount of semantics by clarifying that listName can target a specific list or all lists, and mentions 'optional filtering' which aligns with completed and searchTerm, but it does not significantly enhance parameter understanding beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool retrieves reminders from a specific list or all lists with optional filtering, which is a specific verb+resource. However, it does not differentiate from the sibling 'search_reminders' tool, leaving potential ambiguity about when to use each.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives like search_reminders. The description implies usage for fetching reminders but offers no exclusions or context for choosing between similar tools.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_reminder_listsA

Get all reminder lists available in the Reminders app

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must disclose behavior on its own. It states this is a read operation ('get all'), but it doesn't disclose whether the response includes full list details (e.g., IDs, names) or just summaries, nor any ordering or filtering behavior. For a simple list tool this is limited but understandable.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single clear sentence, front-loaded with the verb and resource, with no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no parameters and no output schema, the description provides the essential purpose. It could clarify return structure, but the overall simplicity of the tool makes the description adequately complete for an agent to select and invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has zero parameters, and the schema is empty with 100% coverage vacuously. Since there are no parameters to explain, the description need not add parameter details; baseline is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'get' and identifies the resource as 'all reminder lists' within the Reminders app, clearly distinguishing from sibling tools that operate on individual reminders.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies this tool is for fetching reminder lists rather than individual reminders, but it does not explicitly state when to use it over alternatives like get_reminders, nor does it mention any exclusions or conditions. Usage context is only implied by the resource naming.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_remindersA

Search for reminders by name or body content

ParametersJSON Schema
NameRequiredDescriptionDefault
searchTermYesTerm to search for in reminder names and bodies

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description must carry the burden of behavioral disclosure. It states that both names and body content are searched, which is useful, but it does not mention return format, pagination, case sensitivity, or any other behavioral traits. This is a minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence that is front-loaded with the action and scope. Every word contributes meaning, and there is no redundancy or filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with one parameter and no output schema or annotations, the description is fairly complete. It states what the tool does and what field it searches, but lacks any information about return values or potential limitations, making it slightly incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage, with searchTerm described as 'Term to search for in reminder names and bodies'. The description adds no new semantics beyond what the schema already provides, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'search' with a clear resource 'reminders' and specifies the scope 'by name or body content'. It effectively distinguishes this tool from sibling tools like get_reminders, which likely lists all reminders without a search critical.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage: when you have a term to find in reminder names or bodies. It doesn't explicitly mention alternatives like get_reminders, but the context is clear enough for an agent to infer when to use this tool versus listing all reminders.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

update_reminderC

Update an existing reminder

ParametersJSON Schema
NameRequiredDescriptionDefault
bodyNoNew body/notes for the reminder
nameNoNew name for the reminder
dueDateNoNew due date in format "MM/DD/YYYY HH:MM AM/PM"
priorityNoNew priority level (0=none, 1=high, 5=medium, 9=low)
completedNoMark reminder as completed or not
reminderIdYesID of the reminder to update

TDQS

C2.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the burden of disclosing behavioral traits. It does not explain whether the update is partial or full, what happens to unspecified fields, whether the operation is reversible, or what the response contains. The mere verb 'update' implies mutation but lacks critical details.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, concise sentence that is easy to parse and front-loaded with the key action. It is not overly verbose, but it is also too sparse to be considered highly effective.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool has no annotations and no output schema, the description must compensate with behavioral and usage context. It does not explain update semantics, return values, or side effects, leaving significant gaps for an agent to safely invoke the tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema has 100% coverage with descriptive parameter comments, so the baseline is 3. The description itself adds no parameter information beyond the schema, but it does not need to because the schema is complete.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Update an existing reminder' clearly states the verb (update) and resource (reminder), which distinguishes it from sibling tools like create_reminder, delete_reminder, and list_reminder_lists. However, it lacks any additional scope or detail that would make it especially informative beyond the obvious.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor any mention of prerequisites, typical use cases, or conditions. It simply states the action without contextual cues.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 6 tool updatesv1.0.0
    • First observedcreate_reminder
    • First observeddelete_reminder
    • First observedget_reminders
    • First observedlist_reminder_lists
    • First observedsearch_reminders
    • First observedupdate_reminder
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.6/5.0

Scored across 6 tools

Disambiguation4/5

Each tool targets a distinct operation (list lists, get reminders, CRUD, search). However, get_reminders with filtering and search_reminders could overlap if an agent wants to filter by text, though the descriptions clarify get_reminders is list-based while search is content-based.

Naming Consistency5/5

All tool names follow a consistent verb_noun snake_case pattern (list_, get_, create_, update_, delete_, search_). The only slight oddity is list_reminder_lists (list lists), but it still adheres to the convention.

Tool Count5/5

Six tools is an appropriate size for a reminders domain, providing list access, full CRUD for reminders, and search. No redundant tools and no significant missing operations for the core purpose.

Completeness4/5

The set covers the full lifecycle of reminders: create, read (with filtering), update, delete, and search. A minor gap is the lack of list management (create/update/delete lists), but that may be outside the intended scope for a reminders automation tool.

Maintenance

ActivityInactive
ResponsivenessUnresponsive

Resources

Related MCP Connectors

Related MCP Servers