Pim MCP

One thin, local MCP server for all your calendars.

Nextcloud · iCloud · Google · any CalDAV, merged into a single view your agent can read and manage.

Quick start · Accounts · Connect · Tools · Guardrails · Providers · Contributing

 you   › Find me an hour on Thursday afternoon and put the dentist there.

agent › find_free_time start=Thu 12:00 end=Thu 18:00 duration_minutes=60 ↳ 13:00–15:30 · 16:15–18:00 › create_event calendar="icloud/personal" title="Dentist" start=Thu 13:00 ↳ ✓ created Thu 13:00–14:00 · icloud/personal

Done. Thursday 13:00 is booked; you're free again from 14:00.

✨ Why

🗂️ One merged view

Every calendar on every account in one sorted list, with recurring events expanded. No more "which account was that in?"

🧳 Portable

One TOML file with no secrets in it. Secrets are references to your OS secret store, env vars or a password manager, so the same config works on every machine.

🪶 Thin and local

Your agent client starts it over stdio when needed. Nothing runs in the background, there's no port open, and no cloud sits in between.

🛡️ Safe by default

Deleting events and anything that emails other people stay off until you allow them. Edits never overwrite changes made elsewhere.

🧭 How it works

flowchart LR

A["🤖 Agent Claude Code · Claude Desktop · Cursor "] -- "MCP · stdio" --> P[" pim-mcp on your machine "] S[("🔐 OS secret store Keychain · Secret Service · DPAPI ")] -. "app passwords / tokens" .-> P P -- CalDAV --> N["☁️ Nextcloud"] P -- CalDAV --> I["🍎 iCloud"] P -- "CalDAV + OAuth" --> G["📅 Google"] P -- CalDAV --> O["🌐 any CalDAV"]

🚀 Quick start

Requires Node.js 22+.

npm install -g pim-mcp                         # 1 · install (or prefix commands with `npx -y`)

pim-mcp init # 2 · write ~/.config/pim-mcp/config.toml pim-mcp secret set pim-mcp/icloud # 3 · store an app password (prompted, not echoed) pim-mcp check # 4 · verify every account claude mcp add pim -s user -- npx -y pim-mcp # 5 · connect your agent

pim-mcp check lists what it found:

✓ nextcloud (nextcloud) — 3 calendar(s)

nextcloud/personal Personal nextcloud/work Work ✓ icloud (icloud) — 2 calendar(s) icloud/family Family icloud/travel Travel

The config lives at ~/.config/pim-mcp/config.toml on every OS (C:\Users\ \.config\pim-mcp\config.toml on Windows). Set PIM_MCP_CONFIG to use another path.

🔐 Secrets

Passwords and tokens never go in the config. It holds a reference instead:

🍎 macOS : login Keychain

Stored as generic passwords in your login Keychain. You can also manage them in Keychain Access, or with security add-generic-password -s pim-mcp -a icloud -w.

🐧 Linux : Secret Service (GNOME Keyring / KWallet)

Needs secret-tool:

sudo apt install libsecret-tools     # Debian / Ubuntu

sudo dnf install libsecret # Fedora sudo pacman -S libsecret # Arch

On a headless machine there's usually no keyring running. Use env: refs (set them in your MCP client's env block) or pass:

password = "cmd:pass show pim-mcp/icloud"

🪟 Windows : DPAPI

Secrets are encrypted with DPAPI, the per-user encryption Credential Manager also uses. They're stored under %APPDATA%\pim-mcp\secrets\, and only your Windows user on this machine can decrypt them. Nothing to install. cmd: refs run in cmd.exe.

👤 Accounts

☁️ Nextcloud (any Nextcloud / ownCloud server)

1. Nextcloud → Settings → Security → Devices & sessions → Create new app password
2. pim-mcp secret set pim-mcp/nextcloud

[[accounts]]

id = "nextcloud" provider = "nextcloud" url = "https://your.next.cloud/remote.php/dav" username = "your-login" password = "keychain:pim-mcp/nextcloud"

🍎 iCloud

1. account.apple.com → Sign-In and Security → App-Specific Passwords
2. pim-mcp secret set pim-mcp/icloud

[[accounts]]

id = "icloud" provider = "icloud" username = "you@icloud.com" # the email you sign into your Apple Account with password = "keychain:pim-mcp/icloud"

📅 Google (one-time OAuth setup)

Google only allows OAuth for CalDAV:

1. Google Cloud Console: create a project and enable the CalDAV API.
2. OAuth consent screen: choose External and add yourself as a test user. Then set the publishing status to In production, because tokens issued in "Testing" mode expire after 7 days. An "unverified app" warning at sign-in is expected for a personal app.
3. Credentials → Create OAuth client ID → Desktop app. Put the client ID in the config and store the secret: pim-mcp secret set pim-mcp/google-client-secret
4. pim-mcp auth google --account google opens your browser and stores the refresh token in your OS secret store.

[[accounts]]

id = "google" provider = "google" username = "you@gmail.com" client_id = "xxxx.apps.googleusercontent.com" client_secret = "keychain:pim-mcp/google-client-secret" refresh_token = "keychain:pim-mcp/google"

🌐 Any other CalDAV server

[[accounts]]

id = "fastmail" provider = "caldav" url = "https://caldav.fastmail.com/" username = "you@fastmail.com" password = "keychain:pim-mcp/fastmail"

Known URLs are in Providers.

🔌 Connect your agent

Claude Code (any OS)

claude mcp add pim -s user -- npx -y pim-mcp

Claude Desktop, Cursor and other GUI clients. Add this to the client's MCP config:

🍎 macOS : ~/Library/Application Support/Claude/claude_desktop_config.json

{

"mcpServers": { "pim": { "command": "npx", "args": ["-y", "pim-mcp"] } } }

GUI apps don't always see your shell's PATH. If the server fails to start, replace npx with the full path from which npx, e.g. /opt/homebrew/bin/npx.

🪟 Windows : %APPDATA%\Claude\claude_desktop_config.json

{

"mcpServers": { "pim": { "command": "cmd", "args": ["/c", "npx", "-y", "pim-mcp"] } } }

npx is a batch script on Windows, so it runs through cmd /c.

🐧 Linux

Claude Desktop isn't available for Linux; use Claude Code or another MCP client with the same command / args as macOS. env: refs go in the client's env block:

"pim": {

"command": "npx", "args": ["-y", "pim-mcp"], "env": { "ICLOUD_PASSWORD": "…" } }

🧰 Tools

| | Tool | What it does | |:-:|---|---| | 📚 | list_calendars | All calendars and their ids (icloud/work). Anywhere a tool takes a calendar, a plain name works too. | | 🗓️ | list_events | Events from all calendars in a range, merged and sorted. Defaults to today through the next 7 days. | | 🔎 | search_events | Text search over title, location and description. | | 📄 | get_event | Full details: description, attendees, organizer, recurrence rule, reminders. | | 🕐 | find_free_time | Free windows of at least N minutes, optionally within working hours. | | ➕ | create_event | Timed or all-day, with recurrence, up to 3 reminders, and busy/free status. | | ✏️ | update_event | Changes only the fields you pass. Recurring events take scope: instance or series. | | 🗑️ | delete_event | Off unless allow_delete = true. Takes the event's title, so approval prompts show its name, and refuses a title that doesn't match the event. |

What agents see:

• Times without an offset are in your configured timezone.
• Output is ISO 8601 with offsets.
• All-day events use YYYY-MM-DD, and their end date is inclusive.

🛡️ Guardrails

timezone = "Europe/Amsterdam"            # default: the system timezone

[guardrails] allow_delete = false # delete_event is refused allow_invites = false # no adding attendees, no editing/deleting events that have them

[[accounts]]

…

read_only = true # no writes to this account at all read_only_calendars = ["Family"] # protect specific calendars hide_calendars = ["Birthdays"] # don't show these at all

• Refusals explain themselves. When a guardrail blocks something, the agent is told which setting would allow it, so it asks you instead of retrying.
• No lost edits. Every write checks the event's ETag. If the event changed elsewhere since it was read, the write fails instead of overwriting.

🌍 Providers

| Outlook · Microsoft 365 · Exchange | 🚧 wanted | no CalDAV; needs a [Microsoft Graph backend](CONTRIBUTING.md#adding-a-no