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/madebydia/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.