jonmmease/jons-mcp-reminders

MCP Server for macOS Reminders

An MCP server for managing macOS Reminders via EventKit.

This FastMCP server provides native access to the macOS Reminders app through the Model Context Protocol (MCP), enabling AI assistants to create, read, update, and delete reminders and lists.

Requirements

• macOS 14.0+ (Sonoma or later)
• Python 3.10+

Installation

# Clone the repository
git clone <your-repo-url>
cd jons-mcp-reminders

# Install with uv
uv pip install -e .

Permissions

On first run, the server will request access to Reminders. You must grant this permission in:

System Settings > Privacy & Security > Reminders

The Terminal app (or your Python environment) must have permission to access Reminders.

Running the Server

uv run jons-mcp-reminders

Adding to Claude Code

# Register the MCP server with Claude Code
claude mcp add jons-mcp-reminders -- uv run --project /path/to/jons-mcp-reminders jons-mcp-reminders

Adding to Claude Desktop

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

{
  "mcpServers": {
    "jons-mcp-reminders": {
      "command": "uv",
      "args": [
        "run",
        "--project",
        "/path/to/jons-mcp-reminders",
        "jons-mcp-reminders"
      ]
    }
  }
}

Replace /path/to/jons-mcp-reminders with the actual path to this repository.

Available Tools

List Management (5 tools)

Reminder CRUD (7 tools)

Batch Operations (3 tools)

Search (1 tool)

Priority Values

Location-Based Reminders

You can create reminders that trigger based on arriving at or leaving a location. The create_reminder and update_reminder tools accept a location parameter with the following fields:

Example: Create reminder with location

await create_reminder(
    title="Buy groceries",
    location={
        "title": "Whole Foods",
        "latitude": 37.7749,
        "longitude": -122.4194,
        "radius": 100.0,
        "proximity": "enter"
    }
)

Example: Remove location from reminder

await update_reminder(reminder_id, clear_location=True)

Note: Location-based reminders require Location Services to be enabled on the device for the triggers to activate.

Known Limitations

1. Sections not supported: EventKit does not expose sections/headers within reminder lists (e.g., "Frozen", "Produce" in a Grocery list). This is a UI-only feature with no public API.

2. Color shifting: Colors may shift slightly (~30 units per RGB channel) due to iCloud color space conversion when syncing. This is expected behavior.

3. Exchange calendars: Reminder IDs on Exchange accounts may change after initial sync. iCloud calendars have stable IDs.

Development

Setup

# Install with dev dependencies
uv pip install -e ".[dev]"

Running Tests

# Run all tests
uv run pytest

# Run integration tests (requires Reminders access)
uv run pytest tests/test_integration.py -v

# Run with coverage
uv run pytest --cov=src

Code Quality

# Type check
uv run mypy src/jons_mcp_reminders

# Format code
uv run black src tests

# Lint code
uv run ruff check src tests

Project Structure

jons-mcp-reminders/
├── src/
│   └── jons_mcp_reminders/
│       ├── __init__.py          # Package exports
│       ├── constants.py         # Configuration constants
│       ├── exceptions.py        # Custom exceptions
│       ├── models.py            # Pydantic models
│       ├── converters.py        # EventKit <-> Python conversions
│       ├── store.py             # ReminderStore singleton
│       ├── server.py            # FastMCP server setup
│       └── tools/
│           ├── __init__.py      # Tool exports
│           ├── lists.py         # List management tools
│           ├── reminders.py     # Reminder CRUD tools
│           ├── batch.py         # Batch operation tools
│           └── search.py        # Search tool
├── tests/
│   ├── conftest.py              # Test fixtures
│   └── test_integration.py      # Integration tests
├── pyproject.toml               # Project configuration
├── CLAUDE.md                    # AI assistant guidance
└── README.md                    # This file

License

MIT