PACKAGE EXPLORERView in registry

agents-calendar

PyPI

CalDAV calendar feeler for agents (CLI + MCP). Stdlib HTTP, no caldav/icalendar libs.

Versions collected1

Direct dependencies1From release 0.1.1

Last observed20 Oct, 23:17 UTC

README

Version 0.1.1 documentation

agents-calendar

CalDAV feeler for agents (CLI + MCP).
Stdlib HTTP. The server expands recurrence. Passwords stay on the host.

Quickstart

pip install agents-calendar && agents-calendar sync --init

Merges MCP into host configs. Prints where credentials go. Does not write secrets into mcp.json. init is the same command.

[!TIP] 🤖 Agent-Driven Setup: Give your coding agent this repo (clone or URL), then tell it to "install and set up agents-calendar."

Source checkouts can also be installed and managed with vand.

What it does

List calendars, list events in a time range, add, update, delete. Recurrence rules stay on the CalDAV server (time-range report). Writes send If-None-Match: * on create and If-Match on update and delete, so a stale etag does not clobber.

The password is never printed, logged, or returned by a tool.

Credentials

Highest priority first:

Process env: CALDAV_URL, CALDAV_USERNAME, CALDAV_PASSWORD, optional CALDAV_CALENDAR
~/.agents/calendar.json (mode 0600)
~/.agents/.env keys CALDAV_*

{
  "url": "https://example.com/dav/calendars/user/calendar/",
  "username": "user",
  "password": "app-password",
  "calendar": "Work"
}

calendar (or CALDAV_CALENDAR) is optional: the collection, by display name or URL, that add writes to. list searches every collection unless --calendar names one. Both commands and the MCP tools accept calendar per call.

CLI and MCP both read this file, so a desktop host does not need the password in its MCP config. A URL that is only a host or principal is resolved through calendar-home-set. add writes into a VEVENT collection, not a reminder collection.

Where it runs

Floor: any MCP client or a terminal. python -m agents_calendar serve is enough. No skills are installed.

Layer	What you get	Who
CLI + MCP	The five tools below, or the same verbs on the CLI	Any MCP host / any shell
Autowire	`sync --init` merges `agents-calendar` when the host config directory already exists, and ensures `~/.cursor/mcp.json`	Cursor, Claude Desktop, Zed (`context_servers`), Antigravity / Gemini, Windsurf, Codex, Roo, Cline

MCP without autowire: point the host at python -m agents_calendar serve.

MCP tools

Primary surface. They mirror the CLI. Password never appears in the JSON.

Tool	What it does
`calendar_calendars`	Collections under the configured URL
`calendar_list`	VEVENTs between ISO `start` and `end`. Returns UTC and local times
`calendar_get`	Get a single VEVENT by `href` with UTC and local times
`calendar_add`	Create. `If-None-Match` so an existing UID is not overwritten
`calendar_update`	Replace. `href` and `etag` come from `calendar_list` or `calendar_get`
`calendar_delete`	Delete. Same `href` + `etag` pair

Six tools. Timezone and daylight saving time (DST) shifts are handled deterministically via Python zoneinfo.

CLI

Machine-readable catalog: python -m agents_calendar --help-json (do not scrape --help).

Command	Purpose
`agents-calendar sync --init`	Merge MCP. Alias: `agents-calendar init`
`agents-calendar calendars`	List collections
`agents-calendar list --from <ISO> --to <ISO>`	Events in that range with local & UTC times
`agents-calendar get --href <href>`	Get event details by href
`agents-calendar add --summary "…" --dtstart <ISO> --dtend <ISO>`	Create. Optional `--location`, `--description`, `--timezone`, `--all-day`
`agents-calendar update --href <href> --etag <etag> …`	Replace fields you pass
`agents-calendar delete --href <href> --etag <etag>`	Delete
`agents-calendar serve`	stdio MCP. Not the default

No subcommand prints help.

ABI

Contract in abi/:

WHY.md — server-side recurrence and etags
LAYOUT.md — credential file
MCP.md — five tools
CLI.md — the same verbs, plus init

Tests

python -m unittest discover tests

License

MIT. See LICENSE.

Downloads & popularity

Awaiting observations

No metric observations yet

Download counts and popularity will appear here as the collector receives them.

Versions 1

Collected releases

Version	Published	Direct dependencies	Open version
0.1.1	10 Oct 2026	1

Package advisories

No matching advisories collected

This describes our collected data; it is not a security assessment.

Repository

PENDING

lolaplex/agents-calendar

Shared repository data · GitHub

License detected in repository: Not collected

Metadata history

Meaningful changes

Current collected state Current

Observed since 20 Oct, 23:17 UTC

No superseded metadata states collected. Unchanged observations do not create new revisions.

Record identity

package:b7d3e3a92d6025fd12f3a18a3950f228605c2284fb83acdc170b00e43d54a55d