calendar-sse-mcp 0.1.8

A Model Context Protocol server for macOS Calendar.app

Calendar SSE MCP

A Model Context Protocol (MCP) server for interacting with macOS Calendar.app through AppleScript.

Features

• List all calendars from macOS Calendar.app
• Get events from specific calendars
• Filter events by date range
• Create, update, and delete calendar events
• Search for events by text query
• Provides both MCP resources and tools for AI assistants
• Includes prompt templates for common operations
• Comprehensive command-line interface for all operations
• Built-in launch agent support for background operation
• JSON API endpoints for programmatic access
• Robust date parsing using dateparser library
• Data validation with Pydantic v2
• Dynamic launch agent detection and installation

Requirements

• macOS (tested on macOS 14 Sonoma and above)
• Python 3.10 or newer
• Calendar.app with at least one calendar set up

Installation

From Source

Clone the repository and install:

git clone https://github.com/yourusername/calendar-sse-mcp.git
cd calendar-sse-mcp
pip install -e .

Using uv

You can install directly using uv, a fast Python package installer:

uv pip install git+https://github.com/HongpengM/calendar-sse-mcp.git

Note: This package will be available on PyPI in the future.

uv pip install calendar-sse-mcp

Using uvx

The easiest way to install and run the calendar service is with uvx:

# Install the server as a Launch Agent with default settings (port 27212)
uvx --from calendar-sse-mcp install-server install

# Customize the installation
uvx --from calendar-sse-mcp install-server install --port 5000 --logdir ~/logs

# Reinstall the package and launch agent (unloads existing agent first)
uvx --from calendar-sse-mcp install-server reinstall

# Update to the latest version (refresh the uvx cache and reinstall)
uvx --refresh --from calendar-sse-mcp install-server reinstall

The installation process:

1. Sets up a launch agent to run the server in the background
2. Configures it to start automatically when you log in
3. Makes the server accessible at http://localhost:27212 by default

Claude Configuration

To add this calendar service to Claude, create the following JSON configuration:

{
  "schema_version": "v1",
  "name": "Calendar",
  "description": "Access and manage events in macOS Calendar.app",
  "provider_uri": "http://localhost:27212",
  "provider_type": "mcp_server",
  "tools": [
    {
      "name": "list_all_calendars",
      "description": "List all available calendars in Calendar.app"
    },
    {
      "name": "search_events",
      "description": "Search for events in Calendar.app by query, calendar name, and date range"
    },
    {
      "name": "create_calendar_event",
      "description": "Create a new event in Calendar.app"
    },
    {
      "name": "update_calendar_event",
      "description": "Update an existing event in Calendar.app"
    },
    {
      "name": "delete_calendar_event",
      "description": "Delete an event from Calendar.app"
    }
  ]
}

Save this as calendar-mcp.json and add it to Claude in your settings.

Command-line Usage

The package provides a comprehensive command-line interface:

# Using uvx (recommended)
uvx --from calendar-sse-mcp calendar-mcp [command] [options]

# Or directly with the module
python -m calendar_sse_mcp [command] [options]

Reinstalling the package

# Simple reinstall (also unloads existing launch agent and reinstalls it)
uvx --from calendar-sse-mcp install-server reinstall

# Reinstall with custom port
uvx --from calendar-sse-mcp install-server reinstall --port 5000 --logdir ~/logs

# Update to the latest version (refresh the uvx cache and reinstall)
uvx --refresh --from calendar-sse-mcp install-server reinstall

Running the server

# Start the MCP server
uvx --from calendar-sse-mcp calendar-mcp server

# Specify host and port
uvx --from calendar-sse-mcp calendar-mcp server --host 0.0.0.0 --port 5000

Installing as a Claude MCP server

# Install as a Claude MCP server
uvx --from calendar-sse-mcp calendar-mcp install

# With a custom name
uvx --from calendar-sse-mcp calendar-mcp install --name "My Calendar"

Setting up as a Launch Agent (background service)

The package includes a built-in command to create and install a Launch Agent:

# Create and install the Launch Agent (using install-server)
uvx --from calendar-sse-mcp install-server launchagent

# Create, install, and immediately load the Agent
uvx --from calendar-sse-mcp install-server launchagent --load

# Customize port and log directory
uvx --from calendar-sse-mcp install-server launchagent --port 5000 --logdir ~/logs

# Alternative using calendar-mcp command
uvx --from calendar-sse-mcp calendar-mcp agent create

# Check the status of the Launch Agent
uvx --from calendar-sse-mcp calendar-mcp agent check

# Show logs
uvx --from calendar-sse-mcp calendar-mcp agent check --show-logs

# Uninstall the Launch Agent
uvx --from calendar-sse-mcp calendar-mcp agent uninstall

# Reinstall the Launch Agent (uninstall and create again)
uvx --from calendar-sse-mcp calendar-mcp agent uninstall && uvx --from calendar-sse-mcp calendar-mcp agent create --load

Managing Calendar Events

# List all calendars
uvx --from calendar-sse-mcp calendar-mcp calendars

# Get events from a calendar
uvx --from calendar-sse-mcp calendar-mcp events "Work"

# Create a new event
uvx --from calendar-sse-mcp calendar-mcp create "Work" "Team Meeting" --start-time 10:00

# Update an event
uvx --from calendar-sse-mcp calendar-mcp update "Work" "EVENT_ID" --summary "Updated Meeting"

# Delete an event
uvx --from calendar-sse-mcp calendar-mcp delete "Work" "EVENT_ID"

# Search for events
uvx --from calendar-sse-mcp calendar-mcp search "meeting" --calendar "Work"

For more details, see the CLI Tools Documentation.

Calendar.app Permissions

The first time you run the server and it attempts to access Calendar.app, macOS will prompt you to grant permissions. You must grant these permissions for the script to work.

1. When prompted, click "OK" to allow access
2. To check or modify permissions later, go to:
   • System Settings > Privacy & Security > Automation
   • Ensure Python/Terminal has permissions to control Calendar.app

Privacy Warning and Disclaimer

IMPORTANT: This software requires full access to your macOS Calendar.app and all its data. Please be aware of the following:

• When you run this software, macOS will prompt you to grant Calendar.app access to uv, Python, or your terminal application
• Granting this permission gives the application complete read and write access to ALL your calendar data
• All calendar events, including potentially sensitive information (meetings, appointments, personal events), will be accessible to this software
• Any application given this access could potentially read, modify, or delete your calendar events

By installing and using this software, you acknowledge:

1. You understand the scope of permissions being granted
2. You accept the potential privacy and security risks involved
3. You are responsible for reviewing the source code or trusting the developer
4. No warranty is provided regarding security, privacy, or data integrity

If you're uncomfortable with these permissions, please do not proceed with installation.

API Reference

MCP Resources

• calendars://list - List all available calendars
• calendar://{name} - Get information about a specific calendar
• events://{calendar_name} - Get all events in a calendar
• events://{calendar_name}/{start_date}/{end_date} - Get events in a date range
• event://{calendar_name}/{event_id} - Get a specific event by ID

JSON API Endpoints

See API Endpoints Documentation for detailed information.

• api://calendars - Get all calendars as a standardized JSON response
• api://events/{calendar_name} - Get events from a calendar as JSON
• api://events/{calendar_name}/{start_date}/{end_date} - Get events in a date range
• api://events/create/{calendar_name}/{summary}/{start_date}/{end_date} - Create a new event
• api://events/update/{event_id}/{calendar_name} - Update an event
• api://events/delete/{event_id}/{calendar_name} - Delete an event

MCP Tools

• list_all_calendars() - List all available calendars
• search_events(query, calendar_name?, start_date?, end_date?) - Search for events
• create_calendar_event(calendar_name, summary, start_date, end_date, location?, description?) - Create a new event
• update_calendar_event(event_id, calendar_name, summary?, start_date?, end_date?, location?, description?) - Update an event
• delete_calendar_event(event_id, calendar_name) - Delete an event

MCP Prompts

• create_event_prompt(calendar_name, summary, date?, start_time?, end_time?, duration_minutes?, location?, description?) - Prompt to create a new event
• search_events_prompt(query, calendar_name?, start_date?, end_date?) - Prompt to search for events

Documentation

• Launch Agent Setup - How to run the server as a background service
• CLI Tools - Comprehensive command-line tool reference
• Date Handling - Information about flexible date parsing with dateparser

Date Parsing

This package uses the dateparser library for robust date parsing, which provides:

• Natural language date parsing ("tomorrow", "next week", etc.)
• Support for relative dates ("3 days from now")
• Multiple date formats (MM/DD/YYYY, YYYY-MM-DD, etc.)
• Time zone awareness

Example date formats supported:

• "2023-05-15" (ISO format)
• "May 15, 2023" (Natural language)
• "tomorrow at 3pm" (Relative with time)
• "next Monday" (Weekday reference)
• "05/15/2023" (US format)
• "15/05/2023" (European format)

Data Validation

The package uses Pydantic v2 for data validation, providing:

• Type checking and validation
• Custom validators
• JSON schema generation
• Serialization/deserialization
• Proper error messages for validation failures

Future Enhancements

• CalDAV support for accessing remote calendars
• Recurring event support
• Calendar sharing features
• Support for attendees and invitations
• Notifications for upcoming events

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.