pim-mcp

Name: pim-mcp
Author: da-the-dev

本地服务

github.com/da-the-dev生产力04 天前更新

代码仓库

关于 pim-mcp

pim-mcp 是本地 MCP 服务，可合并 Nextcloud、iCloud、Google 和 CalDAV 日历，供 Agent 读取和管理。凭据以引用形式保存在 TOML 配置之外，并通过操作限制和 ETag 检查减少高风险或冲突编辑。

主要功能

01将多个日历合并为排序视图
02搜索事件并查看完整详情
03查找空闲时间并创建事件
04按单次或整个系列更新事件
05限制删除、邀请及冲突编辑

适用场景

01查看多个日历账户中的事件
02安排日程前查找空闲时段
03创建或更新重复日历事件
04避免覆盖其他位置的更改

MCP 相关

服务在本地通过 stdio 运行，向 MCP 客户端提供日历工具，由客户端按需启动进程。它连接 Nextcloud、iCloud、Google 及其他 CalDAV 服务。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y pim-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmpim-mcp0.1.0stdio

工具

收录的工具列表 · 更新于 4 天前

此工具无需参数。

详细介绍

一款轻量的本地 MCP 服务，管理你的所有日历。
Nextcloud · iCloud · Google · 任意 CalDAV，合并为一个 Agent 可读取和管理的视图。

快速开始 · 账户 · 连接 · 工具 · 安全措施 · 服务提供方 · 参与贡献

 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.

✨ 为什么选择它

🗂️ 合并视图每个账户中的所有日历都会汇总到一个按时间排序的列表中，并展开重复事件。再也不用疑惑“那个事件在哪个账户里？”了。	🧳 便于迁移一个不含任何机密信息的 TOML 文件。机密信息以引用的形式指向操作系统的机密信息存储区、环境变量或密码管理器，因此同一份配置可在每台设备上使用。
🪶 轻量且本地运行需要时，Agent 客户端会通过 stdio 启动它。它不会在后台运行，不会开放端口，也没有云服务介入。	🛡️ 默认安全删除事件以及任何会向他人发送邮件的操作，默认都处于禁用状态，直到你明确允许。编辑操作绝不会覆盖其他地方所做的更改。

🧭 工作原理

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

所有操作系统上的配置文件都位于 ~/.config/pim-mcp/config.toml（Windows 上为 C:\Users\<you>\.config\pim-mcp\config.toml）。设置 PIM_MCP_CONFIG 可使用其他路径。

🔐 密钥

密码和令牌绝不会写入配置中。配置中保存的是引用：

引用	解析为
`keychain:service/account`	操作系统的密钥存储。最简单的方法：`pim-mcp secret set service/account`
`env:NAME`	环境变量
`cmd:<command>`	命令的输出，例如 `cmd:op read op://Private/iCloud/password`、`cmd:pass show icloud`、`cmd:bw get password icloud`

🍎 macOS：登录钥匙串

作为通用密码存储在登录钥匙串中。你也可以在“钥匙串访问”中管理，或使用 security add-generic-password -s pim-mcp -a icloud -w 管理。

🐧 Linux：Secret Service（GNOME Keyring / KWallet）

需要 secret-tool：

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

在无头机器上通常没有正在运行的密钥环。请使用 env: 引用（在 MCP 客户端的 env 块中设置），或使用 pass：

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

🪟 Windows：DPAPI

密钥使用DPAPI加密，这是 Credential Manager 也会使用的逐用户加密机制。密钥存储在 %APPDATA%\pim-mcp\secrets\ 下，只有这台机器上的 Windows 用户才能解密。无需安装任何内容。cmd: 引用会在 cmd.exe 中运行。

👤 账户

☁️ Nextcloud（任何 Nextcloud / ownCloud 服务）

Nextcloud → 设置 → 安全 → 设备与会话 → 创建新的应用密码
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

account.apple.com → 登录与安全 → App 专用密码
pim-mcp secret set pim-mcp/icloud

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

📅 Google（一次性 OAuth 设置）

Google 仅允许 CalDAV 使用 OAuth：

Google Cloud Console：创建项目并启用 CalDAV API。
OAuth 同意屏幕：选择“外部”，并将自己添加为测试用户。然后将发布状态设为正式版，因为在“测试”模式下签发的令牌会在 7 天后过期。个人应用登录时出现“未经验证的应用”警告是正常情况。
凭据 → 创建 OAuth 客户端 ID → 桌面应用。将客户端 ID 填入配置，并保存密钥：pim-mcp secret set pim-mcp/google-client-secret
pim-mcp auth google --account google 会打开浏览器，并将刷新令牌保存到操作系统的密钥存储中。

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

🌐 其他任何 CalDAV 服务

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

已知 URL 请参见提供商。

🔌 连接你的 Agent

Claude Code（任何操作系统）

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

Claude Desktop、Cursor 和其他图形界面客户端。 将以下内容添加到客户端的 MCP 配置中：

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

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

图形界面应用不一定能读取 shell 的 PATH。如果服务无法启动，请将 npx 替换为 which npx 返回的完整路径，例如 /opt/homebrew/bin/npx。

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

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

npx 在 Windows 上是批处理脚本，因此会通过 cmd /c 运行。

🐧 Linux

Claude Desktop 不支持 Linux；请使用 Claude Code，或使用其他 MCP 客户端，并采用与 macOS 相同的 command / args。env: 引用应放在客户端的 env 块中：

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

## 🧰 工具

	工具	功能
📚	`list_calendars`	所有日历及其 ID（`icloud/work`）。凡是工具需要日历时，也可以直接使用名称。
🗓️	`list_events`	指定时间范围内所有日历中的事件，合并并排序。默认范围为今天至未来 7 天。
🔎	`search_events`	按标题、地点和描述进行文本搜索。
📄	`get_event`	获取完整详情：描述、参与者、组织者、重复规则。
🕐	`find_free_time`	查找至少 N 分钟的空闲时段，可选择限定在工作时间内。
➕	`create_event`	创建定时或全天事件，并可设置重复规则、提醒和忙碌/空闲状态。
✏️	`update_event`	只修改你传入的字段。重复事件需要设置 `scope`：`instance` 或 `series`。
🗑️	`delete_event`	默认关闭；需设置 `allow_delete = true` 才能启用。

Agent 看到的内容：

未带时区偏移的时间使用你配置的 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

拒绝操作时会说明原因。 防护措施阻止某项操作时，会告知 Agent 需要启用哪个设置，因此 Agent 会先询问你，而不是重试。
编辑不会丢失。 每次写入都会检查事件的 ETag。如果事件在读取后被其他地方修改，写入会失败，而不会覆盖更改。

🌍 服务提供商

服务提供商	状态	设置
Nextcloud / ownCloud	✅ 已测试	`nextcloud` · `https://<host>/remote.php/dav`
iCloud	✅ 已测试	`icloud` · 专用 App 密码
Google Calendar	🧪 测试版	`google` · OAuth。尚未用真实账户测试；欢迎反馈
Fastmail	🟡 未测试	`caldav` · `https://caldav.fastmail.com/`
Yahoo	🟡 未测试	`caldav` · `https://caldav.calendar.yahoo.com`
mailbox.org	🟡 未测试	`caldav` · `https://dav.mailbox.org/`
Posteo	🟡 未测试	`caldav` · `https://posteo.de:8443/`
Radicale · Baïkal · SOGo · Synology	🟡 未测试	`caldav` · 你的服务端 DAV URL
Outlook · Microsoft 365 · Exchange	🚧 计划支持	不支持 CalDAV；需要 Microsoft Graph 后端
Proton Calendar	❌ 不适用	不支持 CalDAV 或公共 API

🟡 未测试表示这些服务使用标准 CalDAV，应该可以正常工作，但尚未在 pim-mcp 中确认。试过其中某个服务吗？非常欢迎提交 PR 更新此表。

🗺️ 路线图

通过 CalDAV 支持日历：Nextcloud、iCloud、Google、通用
macOS · Linux · Windows 密钥存储
通过 Microsoft Graph 支持 Outlook / Microsoft 365
邮件：IMAP / SMTP，使用相同的账户和配置
文件：WebDAV（Nextcloud 等）

🤝 参与贡献

欢迎添加服务提供商、修复错误以及确认“可与 X 搭配使用”。开发环境设置、用于测试的临时本地 CalDAV 服务，以及如何添加服务提供商，请参阅 CONTRIBUTING.md。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。