pim-mcp

すべてのカレンダーをまとめる、シンプルなローカル MCP サーバーです。
Nextcloud · iCloud · Google · あらゆる CalDAV をひとつのビューに統合し、エージェントが読み取り・管理できます。

クイックスタート · アカウント · エージェントを接続 · ツール · 安全対策 · プロバイダー · コントリビューション

 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.

✨ 選ばれる理由

🧭 仕組み

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"]

🚀 クイックスタート

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 を実行すると、検出された項目が一覧表示されます。

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

すべての OS で、設定ファイルは ~/.config/pim-mcp/config.toml にあります（Windows では C:\Users\<you>\.config\pim-mcp\config.toml）。別のパスを使うには、PIM_MCP_CONFIG を設定してください。

🔐 シークレット

パスワードやトークンを設定ファイルに直接記述することはありません。設定ファイルには代わりに参照を記述します。

sudo apt install libsecret-tools     # Debian / Ubuntu
sudo dnf install libsecret           # Fedora
sudo pacman -S libsecret             # Arch

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

👤 アカウント

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

[[accounts]]
id = "icloud"
provider = "icloud"
username = "[email protected]"   # the email you sign into your Apple Account with
password = "keychain:pim-mcp/icloud"

[[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"

[[accounts]]
id = "fastmail"
provider = "caldav"
url = "https://caldav.fastmail.com/"
username = "[email protected]"
password = "keychain:pim-mcp/fastmail"

🔌 エージェントを接続する

Claude Code（すべての OS）

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

Claude Desktop、Cursor、その他の GUI クライアント。 クライアントの MCP 設定に以下を追加します。

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

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

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

エージェントに表示される内容：

• オフセットを指定しない時刻は、設定済みの timezone の時刻として扱われます。
• 出力はオフセット付きの ISO 8601 形式です。
• 終日予定の日付は YYYY-MM-DD 形式で、終了日を含みます。

🛡️ 安全策

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

• 拒否の理由を説明します。 安全策によって処理がブロックされると、どの設定を変更すれば許可されるかをエージェントに伝えるため、再試行するのではなくユーザーに確認します。
• 編集内容を失いません。 書き込みのたびに予定の ETag を確認します。読み取り後に別の場所で予定が変更されていた場合、上書きせずに書き込みを失敗させます。

🌍 プロバイダー

🟡 未テストとは、標準的な CalDAV で動作するはずですが、まだ pim-mcp で確認できていないことを意味します。試したことがある方は、この表を更新する PR をぜひお寄せください。

🗺️ ロードマップ

• CalDAV 経由のカレンダー：Nextcloud、iCloud、Google、汎用
• macOS・Linux・Windows のシークレットストア
• Microsoft Graph 経由の Outlook / Microsoft 365
• メール：IMAP / SMTP、同じアカウントと設定を使用
• ファイル：WebDAV（Nextcloud など）

🤝 コントリビューション

新しいプロバイダー、バグ修正、「X で動作する」という確認を歓迎します。開発環境のセットアップ、テスト用の一時的なローカル CalDAV サーバー、プロバイダーの追加方法については、CONTRIBUTING.md をご覧ください。