@datenknoten/caldav-mcp
v2.0.0
Published
CalDAV MCP server: expanded calendar entries in, CalDAV writes out; the agent owns the Obsidian vault
Maintainers
Readme
@datenknoten/caldav-mcp
A CalDAV MCP server for an Obsidian-Tasks workflow.
The server is CalDAV-only: it lists calendars, returns calendar entries already expanded
into single instances, and writes entries back to CalDAV. It never touches your vault — the
agent writes the Markdown, guided by the workflow skill this package ships
(skills/caldav-obsidian). That split is deliberate: the vault is the agent's territory, the
calendar is the server's.
Requirements
- Node.js ≥ 24.
- An OS keyring for the CalDAV passwords — Secret Service (Linux), Keychain (macOS) or Credential Manager (Windows) — or the passwords in the environment instead.
- For iCloud an app-specific password. A 401 with credentials that look correct is almost always the regular Apple ID password.
Install
npm install -g @datenknoten/caldav-mcpEquivalent with other toolchains: aube add -g @datenknoten/caldav-mcp or
mise use -g npm:@datenknoten/caldav-mcp.
Quickstart
Run setup in the directory that should carry the configuration — normally your vault:
cd /path/to/your/vault
caldav-mcp setupsetup is interactive and verifies before it stores. It
- checks every account against its CalDAV server before writing anything,
- offers the live calendar list as a checkbox instead of asking you to type display names,
- stores each password in the OS keyring under
caldav-mcp/<account>, - writes a secret-free, committable
.mcp.jsonwith"command": "caldav-mcp"and"args": ["serve"], - copies the workflow skill to
.claude/skills/caldav-obsidian.
A failed check offers retry, continue-unverified (type the calendar allowlist by hand) or abort.
The skill is not optional. Without it the agent invents its own task-line format and the round trip stops matching.
Manual registration
claude mcp add --transport stdio caldav \
--env CALDAV_ICLOUD_URL=https://caldav.icloud.com \
--env [email protected] \
--env CALDAV_ICLOUD_PASSWORD=app-specific-password \
--env EXPORT_CALENDAR=icloud/Privat \
-- /absolute/path/to/node /absolute/path/to/caldav-mcp serveUse absolute paths. The harness starts subprocesses with a different environment than your
shell, and a node that mise or nvm cannot resolve is the most common cause of "server
disconnected".
caldav-mcp serve and a bare caldav-mcp are the same thing — serve is the default command.
In a development checkout dist/index.js starts the same server and stays supported.
Configuration
Everything comes from the environment. An account is defined by its _URL variable; its id is
<NAME> lowercased.
| Variable | Meaning |
|---|---|
| CALDAV_<NAME>_URL | CalDAV entry point, e.g. https://caldav.icloud.com or https://host/dav.php. Defines an account with id <name>. |
| CALDAV_<NAME>_USERNAME | Account user. |
| CALDAV_<NAME>_PASSWORD | Account password. Optional when the keyring holds one under caldav-mcp/<name>; the variable always wins when set. |
| CALDAV_<NAME>_CALENDARS | Optional comma-separated display-name allowlist. Absent = every calendar of that account. |
| CALDAV_MCP_STATE | Path of the bookkeeping ledger. Default $XDG_STATE_HOME/caldav-mcp/state.json (~/.local/state/…). |
| DEFAULT_TIMEZONE | IANA zone for rendering and for interpreting exported times. Default: the system zone. |
| EXPORT_CALENDAR | Default export target, <account>/<calendar display name>. |
| LOG_LEVEL | pino level, default info. |
At least one account is required. A misconfigured environment aborts startup with a single fatal log line listing every problem at once, not one per run.
Tools
| Tool | What it does |
|---|---|
| list_calendars | Lists the readable and writable calendars as <account>/<name> — the exact strings the other tools expect. |
| list_events | Returns entries for a date window, recurrences already expanded, each with a stable id, its [cal:: …] marker and a ready-made Obsidian-Tasks line. |
| mark_imported | Records that the task lines for those ids now exist in the vault, so the next read does not offer them again. |
| create_events | Creates events from tasks and returns a marker per event to append to the source line. An event identical to an earlier export is refused as duplicate with that marker (allowDuplicate: true forces a second booking). dryRun: true shows the iCalendar payload instead of writing. |
| update_events | Changes summary, date and times of events this server created, refusing to overwrite an event that changed on the server in the meantime. |
Security
- Passwords never land in
.mcp.json. That file stays committable; the secrets live in the OS keyring or in the environment. - stdout is the MCP transport. All logging goes to stderr; a single stray
console.logwould destroy the connection. - Event text is third-party data, not instructions. Summaries, descriptions and locations arrive from whoever wrote the calendar entry and are treated as untrusted content.
- Every pipeline scans the dependency graph with Socket.dev before anything installs it; a policy finding blocks the pipeline. Contributions are scanned the same way — see CONTRIBUTING.md and SECURITY.md.
License
MIT — see LICENSE.
