Calendar App MCP

🚀 Calendar App MCP Server

A MCP (Model Context Protocol) server that provides access to macOS Calendar.app events and reminders, suitable for integration with Claude and other AI assistants.

🚀 Quick Start

This package can be run as an MCP server for integration with Claude and other AI assistants that support the MCP protocol, enabling them to access and interact with your macOS calendar data.

# Run as an MCP server for AI assistant integration
uvx calendar-app-mcp   # Automatically run as an MCP server without parameters
uvx calendar-app-mcp mcp   # Explicitly run the MCP server

Once running, Claude can interact with your calendar data via the MCP protocol, allowing it to:

• Check upcoming events
• Find free time slots
• View event details
• Access reminders
• Filter events by calendar, date range, etc.

✨ MCP Tools and Resources

This package provides several MCP tools and resources:

Tools

• get_events: Retrieve events for a specific date range
• get_reminders: Retrieve reminders for a specific date range
• list_calendars: List all available calendars
• get_today_summary: Get a summary of today's events and reminders
• search: Search for events and reminders containing specific terms
• get_current_time: Get the current date and time in a specified time zone
• convert_time: Convert time from one time zone to another
• list_timezones: List all available time zones, optionally filtered by region

Resources

• calendar://events/{date}: Access events for a specific date
• calendar://calendars: Access the list of available calendars
• datetime://current/{timezone}: Get the current time in a specified time zone

Prompts

• daily_agenda: Generate a prompt to view the daily agenda

✨ Features

• Access macOS Calendar.app events and reminders
• Filter by date range, calendar name, and all-day/busy status
• Output in JSON or Markdown format
• Secure local access to calendar data

📦 Installation

# Install from PyPI
pip install calendar-app-mcp

# Use uv
uv pip install calendar-app-mcp

# Use uvx (execute directly without installation)
uvx calendar-app-mcp calendars
uvx calendar-app-mcp mcp

Available Command Names

After installation, the package provides two command-line executables:

# General calendar app tool - displays help when run without parameters
calendar-app

# MCP-centric variant - starts the MCP server by default when run without parameters
calendar-app-mcp

Both support the same subcommands, but calendar-app-mcp is more suitable for use as an MCP server.

Development Installation

# Clone the repository
git clone https://github.com/rygwdn/calendar-app-mcp.git
cd calendar-app-mcp

# Install the uv package manager if not already installed
# https://github.com/astral-sh/uv

# Install the package in development mode
uv install -e .

# Install with test dependencies (optional)
uv install -e .[tests]

💻 Usage Examples

Basic Usage

# Run as an MCP server
uvx calendar-app-mcp

Advanced Usage

# Run specific tests
python -m pytest tests/unit/utils/test_date_utils.py::TestParseDate::test_valid_date

🔧 Technical Details

Running Tests

Run all tests:

python -m pytest

Generate a coverage report:

python -m pytest --cov=calendar_app

Run a specific test file:

python -m pytest tests/unit/utils/test_date_utils.py

Run a specific test:

python -m pytest tests/unit/utils/test_date_utils.py::TestParseDate::test_valid_date

📦 Publishing to PyPI

To publish a new version to PyPI:

1. Update the version number in pyproject.toml.
2. Run tests to verify everything is working: uv run pytest --black --ruff.
3. Build the package: UV_NO_CONFIG=1 uv run python -m build.
4. Upload to PyPI:

   UV_NO_CONFIG=1 uv run twine upload dist/calendar_app_mcp-X.Y.Z*
   

   Replace X.Y.Z with the actual version number.
5. Verify that the package can be installed: uvx calendar-app-mcp@latest --version.
6. Create and push a version tag: git tag vX.Y.Z && git push origin vX.Y.Z.

For detailed instructions, refer to the CLAUDE.md file.