# synology-calendar-mcp（Synology Calendar CalDAV MCP 服务）

> English version: [README.en.md](./README.en.md)

一个用 **Python** 实现的 [Synology Calendar](https://www.synology.com/)（CalDAV）MCP 服务，把群晖日历的增删查改封装为 MCP 工具，技术栈为官方 `mcp` SDK + `caldav` 库。

所有敏感配置（NAS 地址、DSM 账号、密码）放在 `.env` 里，**绝不写进代码**。

---

## 工具

| 工具 | 说明 | 关键参数 |
|------|------|----------|
| `calendar_list_calendars` | 列出所有日历 | — |
| `calendar_create_event` | 新建事件 | `title`, `dtstart`, `dtend`, `cal_id`(默认 ueakup), `location`, `uid` |
| `calendar_list_events` | 列出某日历事件（可按日期范围筛选） | `cal_id`, `start`, `end` |
| `calendar_get_event` | 按 UID 取单个事件 | `uid`, `cal_id` |
| `calendar_delete_event` | 按 UID 删除事件 | `uid`, `cal_id` |

> 时间默认按 **UTC+8（Asia/Shanghai）** 处理，格式 `YYYY-MM-DDTHH:MM[:SS]`。

---

## 安装

```bash
git clone <your-repo> synology-calendar-mcp
cd synology-calendar-mcp
bash install.sh          # 建 .venv、装依赖、生成 .env（从 .env.example）
vim .env                 # 填入 SYNOLOGY_URL / SYNOLOGY_USER / SYNOLOGY_PASSWORD
```

```dotenv
SYNOLOGY_URL=https://nas.yourdomain.com
SYNOLOGY_USER=your-dsm-username
SYNOLOGY_PASSWORD=your-dsm-password
SYNOLOGY_DEFAULT_CAL_ID=ueakup
```

---

## 在 MCP 宿主中注册（stdio）

把 `command` 指向本项目的 `synology-calendar.sh`（会自动加载 `.env`）：

```json
{
  "mcpServers": {
    "synology-calendar": {
      "command": "/abs/path/to/synology-calendar-mcp/synology-calendar.sh",
      "args": []
    }
  }
}
```

> 也可由宿主直接注入 `SYNOLOGY_*` 环境变量，本项目 server 会优先使用宿主注入的值。

### Hermes Agent

Hermes 通过 stdio 加载本服务。将 `command` 指向项目的 `synology-calendar.sh`
（自动加载 `.env`），凭据通过 `env` 注入：

```bash
hermes config set mcp_servers.synology-calendar.command "/abs/path/to/synology-calendar-mcp/synology-calendar.sh"
hermes config set mcp_servers.synology-calendar.args ""
hermes config set mcp_servers.synology-calendar.env '{"SYNOLOGY_URL": "https://nas.yourdomain.com", "SYNOLOGY_USER": "your-dsm-username", "SYNOLOGY_PASSWORD": "your-dsm-password"}'
hermes gateway restart
```

> `args` 必须留空字符串。凭据也可改为引用宿主 `.env` 变量（如
> `"SYNOLOGY_PASSWORD": "${SYNOLOGY_PASSWORD}"`），由 Hermes 启动时展开。

---

## 许可证

MIT