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) orpip
Dependencies
The required Python packages are listed in pyproject.toml and will be installed automatically:
caldavpython-dateutilfastmcp
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 eventcaldav.event.read: Read an existing eventcaldav.event.update: Update an existing eventcaldav.event.delete: Delete an eventcaldav.event.list: List all events
Journal Operations
caldav.journal.create: Create a new journal entrycaldav.journal.read: Read an existing journal entrycaldav.journal.update: Update an existing journal entrycaldav.journal.delete: Delete a journal entrycaldav.journal.list: List all journal entries
Todo Operations
caldav.todo.create: Create a new todo itemcaldav.todo.read: Read an existing todo itemcaldav.todo.update: Update an existing todo itemcaldav.todo.delete: Delete a todo itemcaldav.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