synology-calendar

Manage Synology Calendar events and todos via API. Supports calendars, events, todos, and contacts. Based on official Calendar API Guide (v5).

Security Scan

The skill's code and instructions match a Synology Calendar client (so functionality is coherent), but there are mismatches in the package metadata/registry (env & dependencies) and missing install guidance that you should review before installing.

Purpose & Capability

Name/description (manage Synology Calendar) align with the provided client.py and SKILL.md: the code implements login, event/todo/contact operations and uses the Synology Calendar API endpoints under the user-provided SYNOLOGY_URL.

Instruction Scope

SKILL.md and client.py only instruct the agent to talk to the Synology/NAS API (login, event/task endpoints) and to read SYNOLOGY_URL/USER/PASSWORD environment variables. There are no instructions to read unrelated system files or to send data to third-party endpoints. SKILL.md references a local PDF in documentation that is not packaged with the skill (minor inconsistency).

Install Mechanism

This is instruction-only (no installer or network download), which is low-risk. However _meta.json lists 'requests' as a required library and Python >=3.7, but there is no install spec to ensure those dependencies are installed; runtime failures or surprises are possible if the environment lacks them.

Credentials

The skill requires sensitive credentials (SYNOLOGY_URL, SYNOLOGY_USER, SYNOLOGY_PASSWORD) according to SKILL.md and _meta.json, which is appropriate for a NAS-calendar client. However the registry metadata in the provided summary incorrectly reported 'Required env vars: none' and 'Primary credential: none' — that mismatch is an incoherence you should resolve before trusting the skill.

Persistence & Privilege

The skill does not request 'always: true', does not persist credentials to disk, and does not modify other skills or system-wide agent settings. It stores SID/did in memory only while running. Autonomous invocation is allowed by default (platform default) but is not combined with other high-risk flags.

What to consider before installing

This package appears to implement a legitimate Synology Calendar client, but check the following before installing: (1) The skill needs SYNOLOGY_URL, SYNOLOGY_USER, and SYNOLOGY_PASSWORD — verify the registry metadata is corrected so you know it's asking for credentials. (2) Ensure the runtime will have Python and the 'requests' library (or install them yourself). (3) Inspect and confirm the SYNOLOGY_URL you provide points to a trusted NAS on your network (prefer HTTPS), and consider creating a least-privileged account for the skill rather than using an admin account. (4) Because the skill uses your NAS credentials, only install from a trusted source; if the package origin is unknown (homepage/source unknown), prefer getting the code directly from a verified repository or vendor. (5) If you plan to allow the agent to call the skill autonomously, be aware it will have access to the NAS credentials in memory while invoked — restrict that capability unless you trust the skill fully.

Synology Calendar API Skill

Overview

Manage Synology Calendar using the official Calendar API.

Documentation: Calendar_API_Guide_enu.pdf

Connection

Environment Variables

export SYNOLOGY_URL="http://{nas_ip}:5000"  # 内网地址
export SYNOLOGY_USER="{username}"
export SYNOLOGY_PASSWORD="your-password"

Quick Start

from client import SynologyCalendar

cal = SynologyCalendar()
cal.login()

# List calendars
calendars = cal.get_calendars()
for c in calendars:
    print(f"{c['cal_id']}: {c['cal_displayname']}")

cal.logout()

---

API Reference

Calendar Operations (SYNO.Cal.Cal)

Method	Description	Status
get_calendars()	List all calendars	✅ Working
get_calendar(cal_id)	Get calendar details	✅ Working
create_calendar(...)	Create calendar	✅ Working
delete_calendar(cal_id)	Delete calendar	✅ Working

Event Operations (SYNO.Cal.Event)

Method	Description	Status
list_events(cal_id_list)	List events	✅ Working
get_event(evt_id)	Get event details	✅ Working
create_event(...)	Create event	✅ Working
delete_event(evt_id)	Delete event	✅ Working

Event Creation Notes:

✅ Working:

• All event types now work correctly with v1 API

⚠️ Critical: SID must be in URL parameter, not JSON body

The Synology Calendar v1 API requires the _sid parameter in the URL query string, not in the JSON body.

create_event Parameters:

Parameter	Type	Required	Example
cal_id	string	✅	/admin/home/
summary	string	✅	Event title
dtstart	int	✅	1770440000
dtend	int	✅	1770443600
is_all_day	bool	✅	false
is_repeat_evt	bool	✅	false
color	string	✅	#D9AE00
description	string	✅	Description
notify_setting	array	✅	[]
participant	array	✅	[]
timezone	string	(if not all-day)	Asia/Shanghai

Example:

# Non-all-day event (working)
cal.create_event(
    cal_id='/{username}/home/',
    summary='Meeting',
    dtstart=now,
    dtend=now + 3600,
    is_all_day=False,
    is_repeat_evt=False,
    description='Team meeting',
    color='#D9AE00',
    timezone='Asia/Shanghai'
)

Todo Operations (SYNO.Cal.Todo)

Method	Description	Status
create_todo(...)	Create task	✅ Working
list_todos(...)	List tasks	✅ Working
get_todo(evt_id)	Get task details	✅ Working
delete_todo(evt_id)	Delete task	✅ Working
complete_todo(evt_id)	Mark complete	✅ Working

Contact Operations (SYNO.Cal.Contact)

Method	Description	Status
list_contacts()	List participants	✅ Working

---

CLI Usage

# Login
python client.py login

# List calendars
python client.py list-calendars

# List todos
python client.py list-todos --cal-id "/{username}/home_todo/"

# Create todo
python client.py create-todo \
  --cal-id "/{username}/home_todo/" \
  --title "Task name"

# Complete todo
python client.py complete-todo --evt-id "1012"

---

Known Issues

Event Creation (Fixed with v1 API)

Previous Issue: Event creation returned error 9009 due to:

1. Using v5 API instead of v1 API
2. Missing original_cal_id parameter
3. SID passed in wrong location (JSON body vs URL parameter)

Solution: Use v1 API with:

• cal_id from get_calendars() response
• original_cal_id = cal_id (for non-shared calendars)
• SID in URL parameter: ?_sid=xxx

---

Calendars

ID	Name	Type
/{username}/home/	My Calendar	event
/{username}/home_todo/	Inbox	todo

---

Links

• Official API Guide