Pim Mcp

io.github.da-the-dev由 GitHub 帳號 da-the-dev 發布v0.2.0更新於 Nov 6, 2026

Local MCP server for your calendars across Nextcloud, iCloud, Google and any CalDAV server.

已驗證STDIO僅桌面效率與工作流溝通與協作

概覽

AI 產生的概覽

本機 MCP 伺服器，將 Nextcloud、iCloud、Google 及其他 CalDAV 行事曆合併，讓助理讀取、搜尋、新增、修改與刪除行程。

可以做什麼
  • 列出所有已設定帳號的行事曆與行程，合併排序並展開重複行程
  • 依標題、地點或描述搜尋行程，並查看單一行程的完整內容
  • 在所有或指定行事曆中找出符合時長需求的空檔
  • 新增與修改定時或全天行程，支援重複規則、提醒與忙碌／空閒狀態
  • 刪除行程，需比對標題，並受帳號層級與行事曆層級的保護設定限制
適用情境
適合在多个 CalDAV 帳號上都有行事曆、希望助理從單一檢視回答排程問題、尋找空檔並安排或調整約會的情境。也適合偏好輕量本機程序、不希望中間經過雲端服務的使用者。
執行需求
需要 Node.js 22 以上版本，透過 npx 或全域安裝以 stdio 在本機執行。需要位於 ~/.config/pim-mcp/config.toml 的 TOML 設定檔（可用 PIM_MCP_CONFIG 變更路徑）並列出帳號。憑證為應用程式專用密碼或 OAuth 權杖，以系統金鑰儲存區、環境變數或指令輸出的參照形式提供；Google 需一次性 OAuth 用戶端設定。需能連線各 CalDAV 伺服器。
安裝前請注意
它會保存行事曆帳號的憑證：密碼與權杖以系統鑰匙圈、環境變數或密碼管理員的參照形式存放，需保護好這些儲存區與設定檔。寫入會改動真實行事曆；刪除以及任何寄信給他人的操作預設關閉，需在保護設定中開啟。Google 支援為 beta，多個列出的服務商尚未測試。不支援 Outlook、Microsoft 365 與 Exchange。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Pim Mcp，將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Desktop only，透過 STDIO。 STDIO 服務會啟動本機處理程序，因此需要 SourceWeft 桌面主機。

其他 MCP 客戶端

參照 儲存庫 中的啟動說明。

README

[pim-mcp: your calendars, in every agent]

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.


[npm] [CI] [MCP Registry] [Node] [Platforms] [License: MIT]

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


text
 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

mermaid
flowchart LR    A["🤖 Agent<br><sub>Claude Code · Claude Desktop · Cursor</sub>"] -- "MCP · stdio" --> P["<b>pim-mcp</b><br><sub>on your machine</sub>"]    S[("🔐 OS secret store<br><sub>Keychain · Secret Service · DPAPI</sub>")] -. "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+.

sh
npm install -g pim-mcp                         # 1 · install (or prefix commands with `npx -y`)pim-mcp init                                   # 2 · write ~/.config/pim-mcp/config.tomlpim-mcp secret set pim-mcp/icloud              # 3 · store an app password (prompted, not echoed)pim-mcp check                                  # 4 · verify every accountclaude mcp add pim -s user -- npx -y pim-mcp   # 5 · connect your agent

pim-mcp check lists what it found:

text
✓ 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\<you>\.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:

ReferenceResolves to
keychain:service/accountyour OS secret store. Easiest: pim-mcp secret set service/account
env:NAMEan environment variable
cmd:<command>a command's output, e.g. cmd:op read op://Private/iCloud/password, cmd:pass show icloud, cmd:bw get password icloud
🍎 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:

sh
sudo apt install libsecret-tools     # Debian / Ubuntusudo dnf install libsecret           # Fedorasudo 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:

toml
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
toml
[[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
toml
[[accounts]]id = "icloud"provider = "icloud"username = "[email protected]"   # the email you sign into your Apple Account withpassword = "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.
toml
[[accounts]]id = "google"provider = "google"username = "[email protected]"client_id = "xxxx.apps.googleusercontent.com"client_secret = "keychain:pim-mcp/google-client-secret"refresh_token = "keychain:pim-mcp/google"
🌐 Any other CalDAV server
toml
[[accounts]]id = "fastmail"provider = "caldav"url = "https://caldav.fastmail.com/"username = "[email protected]"password = "keychain:pim-mcp/fastmail"

Known URLs are in Providers.

🔌 Connect your agent

Claude Code (any OS)

sh
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
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
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:

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

🧰 Tools

ToolWhat it does
📚list_calendarsAll calendars and their ids (icloud/work). Anywhere a tool takes a calendar, a plain name works too.
🗓️list_eventsEvents from all calendars in a range, merged and sorted. Defaults to today through the next 7 days.
🔎search_eventsText search over title, location and description.
📄get_eventFull details: description, attendees, organizer, recurrence rule, reminders.
🕐find_free_timeFree windows of at least N minutes, optionally within working hours.
➕create_eventTimed or all-day, with recurrence, up to 3 reminders, and busy/free status.
✏️update_eventChanges only the fields you pass. Recurring events take scope: instance or series.
🗑️delete_eventOff 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

toml
timezone = "Europe/Amsterdam"            # default: the system timezone
[guardrails]allow_delete  = false                    # delete_event is refusedallow_invites = false                    # no adding attendees, no editing/deleting events that have them
[[accounts]]# …read_only           = true               # no writes to this account at allread_only_calendars = ["Family"]         # protect specific calendarshide_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

ProviderStatusSetup
Nextcloud / ownCloud✅ testednextcloud · https://<host>/remote.php/dav
iCloud✅ testedicloud · app-specific password
Google Calendar🧪 betagoogle · OAuth. Not yet tried with a real account; reports welcome
Fastmail🟡 untestedcaldav · https://caldav.fastmail.com/
Yahoo🟡 untestedcaldav · https://caldav.calendar.yahoo.com
mailbox.org🟡 untestedcaldav · https://dav.mailbox.org/
Posteo🟡 untestedcaldav · https://posteo.de:8443/
Radicale · Baïkal · SOGo · Synology🟡 untestedcaldav · your server's DAV URL
Outlook · Microsoft 365 · Exchange🚧 wantedno CalDAV; needs a Microsoft Graph backend
Proton Calendar❌ n/ano CalDAV or public API

🟡 untested means standard CalDAV that should just work but hasn't been confirmed with pim-mcp yet. Tried one? A PR updating this table is very welcome.

🗺️ Roadmap

  • Calendars over CalDAV: Nextcloud, iCloud, Google, generic
  • macOS · Linux · Windows secret stores
  • Outlook / Microsoft 365 via Microsoft Graph
  • Mail: IMAP / SMTP, same accounts and config
  • Files: WebDAV (Nextcloud, …)

🤝 Contributing

New providers, bug fixes and "it works with X" confirmations are all welcome. See CONTRIBUTING.md for dev setup, a throwaway local CalDAV server for testing, and how to add a provider.


MIT © Aleksey Tkachenko · built for agents, readable by humans

來源：README.md，提交 006f369

工具

8

list_calendars

List every calendar across all configured accounts (Nextcloud, iCloud, Google, …), with ids usable in other tools.

無需輸入參數。

list_events

Events in a time range, merged across all calendars and sorted by start. Recurring events are expanded into occurrences. Defaults to today through the next 7 days.

輸入參數endstartaccountscalendars

search_events

Find events whose title, location or description contains the query (case-insensitive). Defaults to 90 days back through 365 days ahead.

輸入參數endquery必填startcalendars

get_event

Full details of one event (description, attendees, organizer, recurrence rule, reminders).

輸入參數id必填

find_free_time

Free time windows of at least `duration_minutes` across all (or selected) calendars. Events marked free/transparent and cancelled events do not block time.

輸入參數end必填start必填accountscalendarsworking_hoursduration_minutes必填

create_event

Create an event. `start` as a date makes an all-day event. Without `end`, timed events last 1 hour and all-day events 1 day.

輸入參數endbusyrrulestart必填title必填calendar必填locationattendeesdescriptionalarm_minutes

update_event

Change an event. Only the fields you pass change; moving `start` alone keeps the duration. For recurring events pass `scope`.

輸入參數id必填endbusyrrulescopestarttitlelocationattendeesdescriptionalarm_minutes

delete_event

Delete an event. The user reviews this call by its `title`, and a title that does not match the event is refused. For recurring events pass `scope` ("instance" removes one occurrence, "series" removes all).

輸入參數id必填scopetitle必填

版本歷史

2
  1. v0.2.0最新Nov 5, 2026
  2. v0.1.0Oct 25, 2026

評分

已滿足適用檢查項的 90%

該評分衡量此收錄條目的完整程度，依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價，也不表示伺服器安全或目前可用：可連通性是帶日期的檢查結果，評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通25 分
  • 已宣告認證方式10 分

    請在註冊中心條目中宣告憑證請求標頭，或保持端點能夠回應探測，以便判定其認證方式。

  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分