npm package: @kleprevost/caldav-mcp
Description: A CalDAV client using Model Context Protocol (MCP) to expose calendar operations as tools for AI assistants.
Author: kleprevost
Latest version: 0.5.2

# caldav-mcp

<div align="center">

🗓️ A CalDAV Model Context Protocol (MCP) server to expose calendar operations as tools for AI assistants.

[![Release](https://github.com/kleprevost/caldav-mcp/actions/workflows/release.yml/badge.svg)](https://github.com/kleprevost/caldav-mcp/actions/workflows/release.yml)
[![npm version](https://badge.fury.io/js/%40kleprevost%2Fcaldav-mcp.svg)](https://www.npmjs.com/package/@kleprevost/caldav-mcp)
[![MIT License](https://img.shields.io/badge/License-MIT-green.svg)](https://choosealicense.com/licenses/mit/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-purple.svg)](https://modelcontextprotocol.io)
[![semantic-release: angular](https://img.shields.io/badge/semantic--release-angular-e10079?logo=semantic-release)](https://github.com/semantic-release/semantic-release)

</div>

## ✨ Features

- Connect to CalDAV servers
- List calendars
- List calendar events within a specific timeframe
- Create calendar events
- Delete calendar events by UID

## Setup

```
{
  "mcpServers": {
    ...,
    "calendar": {
      "command": "npx",
      "args": [
        "@kleprevost/caldav-mcp"
      ],
      "env": {
        "CALDAV_BASE_URL": "<CalDAV server URL>",
        "CALDAV_USERNAME": "<CalDAV username>",
        "CALDAV_PASSWORD": "<CalDAV password>"
      }
    }
  }
}
```

## Development

### Quick Start

Run the MCP server in development mode with auto-reload:
```bash
npm run dev
```

This will run the TypeScript code directly with watch mode and automatically load environment variables from `.env`.

### Manual Build

Alternatively, you can compile TypeScript to JavaScript and run it:

1. Compile:
```bash
npx tsc
```

2. Run:
```bash
node dist/index.js
```

## Available Tools

### create-event

Creates a new calendar event.

Parameters:
- `summary`: String - Event title/summary
- `start`: DateTime string - Event start time
- `end`: DateTime string - Event end time

Returns:
- The unique ID of the created event

### list-events

Lists events within a specified timeframe.

Parameters:
- `start`: DateTime string - Start of the timeframe
- `end`: DateTime string - End of the timeframe
- `calendarUrl`: String - URL of the calendar

Returns:
- `events`: A list of events that fall within the given timeframe, each containing:
  - `uid`: Unique identifier for the event (required for deletion)
  - `summary`: Event title/summary
  - `start`: Event start time
  - `end`: Event end time
  - `wholeDay`: `true` if this is an all-day event
  - `isRecurring`: `true` if this is an instance of a recurring event
- `warning` *(optional)*: Present when recurring events are returned. Indicates that deleted or individually modified occurrences (EXDATE/RECURRENCE-ID) may not be reflected accurately.

### delete-event

Deletes an event from the calendar.

Parameters:
- `uid`: String - Unique identifier of the event to delete (obtained from list-events)
- `calendarUrl`: String - URL of the calendar

Returns:
- Confirmation message when the event is successfully deleted

### list-calendars

Lists all available calendars.

Parameters: none

Returns:
- List of all available calendars

## License

MIT