128 lines
3.6 KiB
Markdown
128 lines
3.6 KiB
Markdown
# MCP CalDAV Server
|
|
|
|
An Model Context Protocol (MCP) server that connects to a CalDAV server (tested with Baikal) to manage calendars and events.
|
|
|
|
## Features
|
|
|
|
- **List Calendars**: View all available calendars.
|
|
- **List Events**:
|
|
- Filter by specific calendar or search **globally across all calendars**.
|
|
- Filter by time range (start/end date).
|
|
- **Manage Events**:
|
|
- Create new events.
|
|
- Update existing events.
|
|
- Delete events.
|
|
|
|
## Prerequisites
|
|
|
|
- **Python 3.14** or higher
|
|
- **uv** (Universal Python Package Manager)
|
|
|
|
## Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository_url>
|
|
cd MCP-CalDAV
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
uv sync
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Create a `.env` file in the root directory with your CalDAV credentials:
|
|
|
|
```env
|
|
CALDAV_URL=http://your-server:port/dav.php
|
|
CALDAV_USERNAME=YourUsername
|
|
CALDAV_PASSWORD=YourPassword
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Running Manually
|
|
|
|
#### Standard I/O (Default)
|
|
You can run the server directly using `uv`. It communicates via standard input/output (stdio), so running it directly in a terminal will just wait for input.
|
|
|
|
```bash
|
|
uv run src/server.py
|
|
```
|
|
|
|
#### HTTP (SSE)
|
|
To run the server over HTTP (Server-Sent Events) - useful for testing with Postman/Inspector or remote access:
|
|
|
|
```bash
|
|
uv run uvicorn src.server:mcp.sse_app --host 0.0.0.0 --port 8000
|
|
```
|
|
**Endpoint:** `http://localhost:8000/sse`
|
|
|
|
### Docker Deployment
|
|
|
|
You can run the server using Docker and Docker Compose. Environment variables are loaded from the `.env` file.
|
|
|
|
**Build and Run (STDIO Mode by default):**
|
|
```bash
|
|
docker compose up --build
|
|
```
|
|
|
|
**Switching Modes:**
|
|
The container supports two modes via the `MCP_MODE` environment variable:
|
|
- `STDIO` (default): Runs the script via standard I/O.
|
|
- `SSE`: Runs the HTTP server on port 8000.
|
|
|
|
To run in SSE mode (e.g., for HTTP access):
|
|
```bash
|
|
docker run -e MCP_MODE=SSE -p 8000:8000 --env-file .env mcp-caldav
|
|
```
|
|
|
|
### Configuring an MCP Client
|
|
|
|
To use this with an MCP client (like Claude Desktop or another MCP-compatible app), add the following configuration to your client's settings (e.g., `claude_desktop_config.json`):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"caldav": {
|
|
"command": "uv",
|
|
"args": [
|
|
"--directory",
|
|
"C:\\Users\\LagoWorkStation\\OneDrive\\Documentos\\MCP-CalDAV",
|
|
"run",
|
|
"src/server.py"
|
|
]
|
|
}
|
|
}
|
|
}
|
|
```
|
|
*Note: Adjust the absolute path to point to your project directory.*
|
|
|
|
## Available Tools
|
|
|
|
- **`get_current_time()`**
|
|
- Returns the current local machine time in ISO format.
|
|
|
|
- **`list_calendars()`**
|
|
- Returns a list of all calendars the user has access to.
|
|
|
|
- **`list_events(calendar_name=None, start_date=None, end_date=None)`**
|
|
- Lists events.
|
|
- `calendar_name` (optional): Name of the calendar. If omitted, searches **ALL** calendars.
|
|
- `start_date` (optional): Start of the range (YYYY-MM-DD or ISO).
|
|
- `end_date` (optional): End of the range.
|
|
|
|
- **`create_event(calendar_name, summary, start_time, end_time, description="", all_day=False, recurrence=None)`**
|
|
- Creates an event.
|
|
- `all_day` (optional, bool): Set to `True` for all-day events (start/end times treated as dates).
|
|
- `recurrence` (optional, str): RRULE string (e.g., `FREQ=DAILY;COUNT=10` or `FREQ=WEEKLY;BYDAY=MO,WE`).
|
|
|
|
- **`update_event(calendar_name, event_uid, summary=None, start_time=None, end_time=None, description=None, all_day=None, recurrence=None)`**
|
|
- Updates an event by UID.
|
|
- `all_day` (optional, bool): Set to `True`/`False` to change event type.
|
|
- `recurrence` (optional, str): Update the recurrence rule.
|
|
- **`delete_event(calendar_name, event_uid)`**
|
|
- Deletes an event by UID.
|