MCP CalDAV STDIO Application

A Python-based MCP (Model Communication Protocol) application that provides CRUD operations for events, journals, and todos using the caldav Python library.

Prerequisites

• Python 3.8 or higher

• uv (optional, for fast installation) or pip

Dependencies

The required Python packages are listed in pyproject.toml and will be installed automatically:

• caldav

• python-dateutil

• fastmcp

Installation Options

You can install the application using uv (recommended) or pip.

Using uv (recommended)

uv pip install radicale-mcp

Using pip

pip install radicale-mcp

From source

git clone https://github.com/TheGreatGooo/radicale-mcp.git
cd radicale-mcp
uv pip install -e .

Using uvx (run directly from GitHub)

uvx radicale_mcp@git+https://github.com/TheGreatGooo/radicale-mcp

Features

• MCP Protocol Support: Communicates over STDIO using the Model Communication Protocol

• CalDAV Integration: Connects to any CalDAV server (like Radicale)

• Full CRUD Operations: Create, Read, Update, and Delete for events, journals, and todos

• Standard Data Models: Well-defined models for events, journals, and todos

• Error Handling: Comprehensive error handling and logging

• Configuration Management: Flexible configuration via files and environment variables

Architecture

┌─────────────────┐    ┌──────────────────┐    ┌──────────────────┐
│   MCP Client    │    │  MCP CalDAV      │    │   CalDAV Server  │
│                 │    │  Application     │    │                  │
│  STDIO Input    │───▶│  (this app)      │───▶│  (e.g. Radicale) │
│  JSON Messages  │    │                  │    │                  │
│                 │◀───│                  │◀───│                  │
│  STDIO Output   │    │                  │    │                  │
└─────────────────┘    └──────────────────┘    └──────────────────┘

Configuration

The application supports configuration through:

• Environment variables

• Configuration file (config/settings.json)

Environment Variables

• CALDAV_SERVER_URL: CalDAV server URL (default: http://localhost:5232)

• CALDAV_USERNAME: Username for authentication (default: user)

• CALDAV_PASSWORD: Password for authentication (default: ``)

• CALDAV_USE_SSL: Whether to use SSL (default: true)

• LOG_LEVEL: Logging level (default: INFO)

Configuration File

Create config/settings.json:

{
  "server_url": "http://localhost:5232",
  "username": "user",
  "password": "",
  "use_ssl": true,
  "log_level": "INFO"
}

Usage

The application runs as an MCP server by default. To start it:

python -m src.server

Or simply:

radicale_mcp

The application will listen on STDIO for MCP protocol messages. It supports the following methods:

Event Operations

• caldav.event.create: Create a new event

• caldav.event.read: Read an existing event

• caldav.event.update: Update an existing event

• caldav.event.delete: Delete an event

• caldav.event.list: List all events

Journal Operations

• caldav.journal.create: Create a new journal entry

• caldav.journal.read: Read an existing journal entry

• caldav.journal.update: Update an existing journal entry

• caldav.journal.delete: Delete a journal entry

• caldav.journal.list: List all journal entries

Todo Operations

• caldav.todo.create: Create a new todo item

• caldav.todo.read: Read an existing todo item

• caldav.todo.update: Update an existing todo item

• caldav.todo.delete: Delete a todo item

• caldav.todo.list: List all todo items

Example Request

{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "caldav.event.create",
  "params": {
    "title": "Team Meeting",
    "description": "Weekly team sync",
    "start_time": "2023-10-15T10:00:00",
    "end_time": "2023-10-15T11:00:00",
    "location": "Conference Room A"
  }
}

Example Response

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "id": "event-12345",
    "status": "created"
  }
}

Development

Project Structure

radicale-mcp/
├── src/main.py                 # Main application entry point
├── requirements.txt        # Python dependencies
├── config/                 # Configuration files
│   └── settings.json      # Application settings
├── src/                    # Source code
│   ├── __init__.py
│   ├── caldav_client.py    # CalDAV connection and operations
│   ├── models/             # Data models
│   │   ├── __init__.py
│   │   ├── event.py        # Event data model
│   │   ├── journal.py      # Journal data model
│   │   └── todo.py         # Todo data model
│   ├── operations/         # CRUD operations
│   │   ├── __init__.py
│   │   ├── event_ops.py    # Event CRUD operations
│   │   ├── journal_ops.py  # Journal CRUD operations
│   │   └── todo_ops.py     # Todo CRUD operations
│   ├── stdio_interface.py  # MCP STDIO protocol implementation
│   ├── config_manager.py   # Configuration management
│   └── error_handler.py    # Error handling and logging
└── docs/                   # Documentation
    ├── architecture.md
    ├── project_structure.md
    ├── data_models.md
    └── mcp_protocol.md

FastMCP Integration

This application demonstrates how to integrate with the FastMCP library. The src/server.py file shows:

• How to create an MCP server instance

• How to define tools that can be called by MCP clients

• Integration with existing CalDAV functionality

To run the FastMCP server:

python -m server

License

MIT