Apple Reminders MCP Server

An MCP (Model Context Protocol) server that provides programmatic access to Apple Reminders via SSE (Server-Sent Events) transport. Built for integration with Poke.com and other MCP clients.

Features

• ✅ Full access to Apple Reminders via EventKit

• ✅ SSE transport for real-time communication

• ✅ API key authentication

• ✅ Rate limiting and security headers

• ✅ Swift-based native macOS integration

• ✅ Comprehensive reminder management (create, read, update, delete, complete)

• ✅ Reminder list management

• ✅ Advanced filtering (by list, date, completion status, search)

Requirements

• macOS 12.0 or later

• Node.js 18.0 or later

• Swift 5.9 or later (comes with Xcode Command Line Tools)

• npm or yarn

Installation

1. Clone the repository

   git clone https://github.com/meimakes/apple-mcp-server.git
   cd apple-mcp-server

2. Install dependencies

   npm install

3. Generate API key

   node -e "console.log(require('crypto').randomBytes(32).toString('base64url'))"

4. Configure environment

   Copy .env.example to .env and add your generated API key:

   cp .env.example .env

   Edit .env:

   PORT=3000
   API_KEY=your_generated_key_here
   LOG_LEVEL=info

5. Build the project

   npm run build

   This will:

   • Compile TypeScript to JavaScript

   • Build the Swift binary for EventKit integration

Usage

Starting the Server

npm start

The server will start on the configured port (default: 3000) and display:

SSE server listening on port 3000
Health check: http://localhost:3000/
SSE endpoint: http://localhost:3000/sse

Setting up ngrok (for remote access)

To make the server accessible from Poke.com or other external services:

# Install ngrok if you haven't already
brew install ngrok

# Start ngrok tunnel
ngrok http 3000

Copy the HTTPS URL (e.g., https://abc123.ngrok.io) for use in Poke.com configuration.

Configuring Poke.com

1. Go to Poke.com connector settings

2. Add a new MCP connector:

   • Name: Apple Reminders

   • Endpoint URL: https://your-ngrok-url.ngrok.io/sse

   • API Key: Your generated API key from .env

Permissions

On first run, the Swift binary will request access to Reminders. You'll see a system prompt:

1. Click "OK" to grant access

2. Alternatively, go to System Settings > Privacy & Security > Reminders

3. Ensure the terminal app or the Swift binary has access

Available Tools

1. list_reminder_lists

Get all reminder lists.

Example:

{}

Returns:

[
  {
    "id": "...",
    "name": "Personal",
    "color": "#FF0000",
    "count": 5
  }
]

2. create_reminder_list

Create a new reminder list.

Parameters:

• name (required): Name of the list

• color (optional): Hex color code (e.g., "#FF0000")

Example:

{
  "name": "Shopping",
  "color": "#00FF00"
}

3. list_reminders

List reminders with optional filtering.

Parameters:

• listId (optional): Filter by list ID

• listName (optional): Filter by list name

• showCompleted (optional): Include completed reminders (default: false)

• dueWithin (optional): Filter by due date - "today", "tomorrow", "this-week", "overdue", "no-date"

• search (optional): Search in title and notes

Example:

{
  "listName": "Personal",
  "showCompleted": false,
  "dueWithin": "today"
}

4. create_reminder

Create a new reminder.

Parameters:

• title (required): Title of the reminder

• listId (optional): ID of the list

• listName (optional): Name of the list

• notes (optional): Additional notes

• dueDate (optional): ISO 8601 date string

• dueDateIncludesTime (optional): Whether the due date includes time

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

• url (optional): Associated URL

Example:

{
  "title": "Buy groceries",
  "listName": "Shopping",
  "notes": "Milk, eggs, bread",
  "dueDate": "2025-11-20T10:00:00Z",
  "dueDateIncludesTime": true,
  "priority": 1
}

5. update_reminder

Update an existing reminder.

Parameters:

• id (required): ID of the reminder

• title (optional): New title

• notes (optional): New notes (null to clear)

• dueDate (optional): New due date (null to clear)

• dueDateIncludesTime (optional): Whether due date includes time

• priority (optional): New priority

• url (optional): New URL (null to clear)

• moveToListId (optional): Move to different list

Example:

{
  "id": "...",
  "title": "Buy groceries and supplies",
  "priority": 5
}

6. complete_reminder

Mark a reminder as complete or incomplete.

Parameters:

• id (required): ID of the reminder

• completed (required): true or false

Example:

{
  "id": "...",
  "completed": true
}

7. delete_reminder

Delete a reminder permanently.

Parameters:

• id (required): ID of the reminder

Example:

{
  "id": "..."
}

API Endpoints

GET /

Health check endpoint (no authentication required).

Returns server status and active session count.

GET /sse

SSE endpoint for MCP client connections (requires authentication).

Include API key in x-api-key header.

POST /messages

Message handling endpoint (requires authentication).

Include API key in x-api-key header.

Authentication

All protected endpoints require an API key in the x-api-key header:

curl -H "x-api-key: your_api_key_here" http://localhost:3000/sse

Error Codes

• 401 Unauthorized - Missing API key

• 403 Forbidden - Invalid API key

• 429 Too Many Requests - Rate limit exceeded (100 requests per 15 minutes)

Security

• ✅ API key authentication on all protected endpoints

• ✅ Rate limiting (100 requests per 15 min per IP)

• ✅ Security headers via Helmet

• ✅ HTTPS via ngrok for remote access

• ✅ Input validation via Zod schemas

• ✅ Session timeout after 30 minutes of inactivity

Development

Project Structure

apple-reminders-mcp/
├── src/
│   ├── index.ts                 # Entry point
│   ├── config.ts                # Configuration
│   ├── types.ts                 # TypeScript types
│   ├── server/
│   │   ├── sse.ts              # SSE server
│   │   └── session.ts          # Session management
│   ├── middleware/
│   │   └── auth.ts             # Authentication
│   ├── mcp/
│   │   ├── server.ts           # MCP server
│   │   ├── tools.ts            # Tool definitions
│   │   └── handlers.ts         # Tool handlers
│   ├── utils/
│   │   ├── logger.ts           # Logging
│   │   └── swift-bridge.ts    # Swift communication
│   └── swift/
│       ├── Models.swift         # Data models
│       ├── RemindersManager.swift # EventKit integration
│       ├── main.swift           # Swift entry point
│       └── build.sh             # Build script
├── .env.example
├── package.json
├── tsconfig.json
└── README.md

Scripts

• npm run build:ts - Compile TypeScript

• npm run build:swift - Build Swift binary

• npm run build - Build both TypeScript and Swift

• npm start - Start the server

• npm run dev - Build and start

• npm run clean - Clean build artifacts

Rebuilding Swift Binary

If you make changes to Swift files:

npm run build:swift

Logging

Set log level in .env:

LOG_LEVEL=debug  # debug, info, warn, error

Troubleshooting

Permission Denied Error

If you see a permission error:

1. Go to System Settings > Privacy & Security > Reminders

2. Add your terminal app or the Swift binary

3. Restart the server

Swift Binary Not Found

npm run build:swift

Port Already in Use

Change the port in .env:

PORT=3001

ngrok Connection Issues

Make sure ngrok is installed and running:

ngrok http 3000

TypeScript Compilation Errors

Clean and rebuild:

npm run clean
npm run build

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.