MCP CalDAV Server

1# MCP CalDAV Server
2 
3Universal MCP server for CalDAV protocol integration. Works with any CalDAV-compatible calendar server including Yandex Calendar, Google Calendar (via CalDAV), Nextcloud, ownCloud, Apple iCloud, and others.
4 
5> 📖 **Quick Start**: See [QUICKSTART.md](QUICKSTART.md) for a quick guide to get started with `uv`.
6> 🔧 **Cursor Setup**: See [CURSOR_SETUP.md](CURSOR_SETUP.md) for detailed Cursor IDE configuration instructions.
7 
8## Features
9 
10- List available calendars
11- Create calendar events with reminders and attendees
12- Get events for today, week, or custom date range
13- Works with any CalDAV-compatible server (Yandex, Google, Nextcloud, ownCloud, iCloud, etc.)
14 
15## Installation
16 
17### Using uv (Recommended)
18 
19First, install uv if you haven't already:
20 
21**macOS/Linux:**
22 
23```bash
24curl -LsSf https://astral.sh/uv/install.sh | sh
25```
26 
27**Windows:**
28 
29```powershell
30powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
31```
32 
33Then install the project:
34 
35```bash
36uv sync --dev
37```
38 
39This will:
40 
41- Create a virtual environment (`.venv`)
42- Install all dependencies including dev dependencies
43- Generate a `uv.lock` file
44 
45### Using uvx (Run without installation)
46 
47You can also run the server directly without installing it:
48 
49```bash
50uvx mcp-caldav
51```
52 
53### Using pip
54 
55```bash
56pip install -e .
57```
58 
59## Configuration
60 
61Set the following environment variables:
62 
63```bash
64export CALDAV_URL="https://caldav.example.com/"
65export CALDAV_USERNAME="your-username"
66export CALDAV_PASSWORD="your-password"
67```
68 
69### CalDAV Server URLs
70 
71Common CalDAV server URLs:
72 
73- **Yandex Calendar**: `https://caldav.yandex.ru/`
74- **Google Calendar**: `https://apidata.googleusercontent.com/caldav/v2/` (requires OAuth setup)
75- **Nextcloud**: `https://your-domain.com/remote.php/dav/calendars/username/`
76- **ownCloud**: `https://your-domain.com/remote.php/dav/calendars/username/`
77- **Apple iCloud**: `https://caldav.icloud.com/` (requires app-specific password)
78- **FastMail**: `https://caldav.fastmail.com/dav/calendars/user/`
79 
80**Note**: Some servers require app-specific passwords instead of regular passwords. Check your calendar provider's documentation for CalDAV setup instructions.
81 
82## Usage
83 
84### IDE Integration (Cursor)
85 
86To use this MCP server in Cursor:
87 
881. Open Cursor Settings → Features → MCP Servers → + Add new global MCP server
892. Add the following configuration:
90 
91**Using uvx (Recommended - no installation needed):**
92 
93```json
94{
95  "mcpServers": {
96    "mcp-caldav": {
97      "command": "uvx",
98      "args": ["mcp-caldav"],
99      "env": {
100        "CALDAV_URL": "https://caldav.example.com/",
101        "CALDAV_USERNAME": "your-username",
102        "CALDAV_PASSWORD": "your-password"
103      }
104    }
105  }
106}
107```
108 
109**Using local installation (after `uv sync` or `pip install`):**
110 
111```json
112{
113  "mcpServers": {
114    "mcp-caldav": {
115      "command": "mcp-caldav",
116      "env": {
117        "CALDAV_URL": "https://caldav.example.com/",
118        "CALDAV_USERNAME": "your-username",
119        "CALDAV_PASSWORD": "your-password"
120      }
121    }
122  }
123}
124```
125 
126**Using local development version:**
127 
128```json
129{
130  "mcpServers": {
131    "mcp-caldav": {
132      "command": "uv",
133      "args": ["run", "--directory", "/path/to/caldav", "mcp-caldav"],
134      "env": {
135        "CALDAV_URL": "https://caldav.example.com/",
136        "CALDAV_USERNAME": "your-username",
137        "CALDAV_PASSWORD": "your-password"
138      }
139    }
140  }
141}
142```
143 
144**Example for Yandex Calendar:**
145 
146```json
147{
148  "mcpServers": {
149    "mcp-caldav": {
150      "command": "uvx",
151      "args": ["mcp-caldav"],
152      "env": {
153        "CALDAV_URL": "https://caldav.yandex.ru/",
154        "CALDAV_USERNAME": "your-username@yandex.ru",
155        "CALDAV_PASSWORD": "your-app-password"
156      }
157    }
158  }
159}
160```
161 
162> **⚠️ Note**: Yandex Calendar has aggressive rate limiting (60 seconds per MB since 2021).
163> Write operations (create/update/delete) may experience 504 timeouts, so space out requests and introduce manual delays.
164> For write-heavy workloads, consider using Google Calendar or Nextcloud instead.
165> See [PROVIDER_NOTES.md](PROVIDER_NOTES.md) for details.
166>
167> **Testing status**: End-to-end tests currently run only against Yandex Calendar. Other CalDAV providers follow the same protocol and should work, but they have not been integration-tested yet.
168 
169**Example for Nextcloud:**
170 
171```json
172{
173  "mcpServers": {
174    "mcp-caldav": {
175      "command": "uvx",
176      "args": ["mcp-caldav"],
177      "env": {
178        "CALDAV_URL": "https://your-domain.com/remote.php/dav/calendars/username/",
179        "CALDAV_USERNAME": "your-username",
180        "CALDAV_PASSWORD": "your-password"
181      }
182    }
183  }
184}
185```
186 
187### As MCP Server
188 
189The server can be used with MCP-compatible clients:
190 
191**Using uv (after `uv sync`):**
192 
193```bash
194uv run mcp-caldav
195```
196 
197**Note:** `uvx` works only with published packages from PyPI. For local development, use `uv run mcp-caldav` after `uv sync`.
198 
199**Using pip (after installation):**
200 
201```bash
202mcp-caldav
203```
204 
205Or with custom options:
206 
207```bash
208uv run mcp-caldav --caldav-url "https://caldav.example.com/" \
209                   --caldav-username "your-username" \
210                   --caldav-password "your-password" \
211                   --verbose
212```
213 
214### Available Tools
215 
216**Basic Operations:**
217 
218- `caldav_list_calendars` - List all available calendars
219- `caldav_create_event` - Create a new calendar event (supports recurrence, categories, priority, attendees)
220- `caldav_get_events` - Get events for a date range (returns extended fields: UID, categories, priority, attendees, recurrence)
221- `caldav_get_today_events` - Get events for today
222- `caldav_get_week_events` - Get events for the week
223 
224**Advanced Operations:**
225 
226- `caldav_get_event_by_uid` - Get a specific event by its UID
227- `caldav_delete_event` - Delete an event by UID
228- `caldav_search_events` - Search events by text, attendees, or location
229 
230**Features Supported:**
231 
232- Recurring events (RRULE) - Daily, Weekly, Monthly, Yearly patterns
233- Categories/Tags - Organize events with categories
234- Priority - Set priority levels (0-9, 0 = highest)
235- Attendees with statuses - Track acceptance status (ACCEPTED/DECLINED/TENTATIVE/NEEDS-ACTION)
236- Reminders - Multiple reminders per event
237 
238## Development
239 
240### Code Quality
241 
242This project uses several tools to ensure code quality:
243 
244- **mypy** - Static type checking with strict rules
245- **ruff** - Fast linting and code formatting
246- **pre-commit** - Automatic checks before commits
247 
248**Run quality checks:**
249 
250```bash
251# Install dev dependencies
252uv sync --group dev
253 
254# Run all checks
255make check
256 
257# Or individually
258make lint
259make format
260make type-check
261 
262# Or using pre-commit
263make pre-commit-run
264```
265 
266**Setup pre-commit hooks:**
267 
268```bash
269uv run pre-commit install
270```
271 
272See [CODE_QUALITY.md](CODE_QUALITY.md) for detailed information.
273 
274### Running Tests
275 
276**Unit tests (with mocks):**
277 
278```bash
279make test
280# or
281make test-unit
282```
283 
284**E2E tests (require real CalDAV server):**
285 
286```bash
287# Create .env.e2e file with your credentials, then:
288make test-e2e
289```
290 
291**All tests:**
292 
293```bash
294make test
295```
296 
297**With coverage:**
298 
299```bash
300make test-cov        # Terminal report
301make coverage-html   # HTML report
302```
303 
304See [tests/e2e/README.md](tests/e2e/README.md) for more details on e2e tests.
305 
306### Project Structure
307 
308```
309caldav/
310├── src/
311│   └── mcp_caldav/
312│       ├── __init__.py      # Main entry point
313│       ├── server.py        # MCP server implementation
314│       └── client.py         # CalDAV client wrapper
315├── tests/
316│   ├── test_server.py       # Server unit tests
317│   ├── test_client.py       # Client unit tests
318│   └── e2e/                 # End-to-end tests with real server
319│       ├── test_client_e2e.py
320│       └── conftest.py
321├── pyproject.toml           # Project configuration
322├── Makefile                 # Development commands
323└── README.md                # This file
324```
325 
326## License
327 
328See LICENSE file for details.
329