AgentCalendar

Headless MCP CalDAV calendar server for AI agents. Sibling to AgentMail: same credential boundary, same stdio-only architecture, no web UI.

What it does

• Reads, searches, and writes CalDAV events directly on the remote server.

• Interactive tools do not read or write a local event mirror. SQLite stores account metadata and an opaque SecretFabric secretRef only for the allowlist.

• There is no background sync worker, no sync interval, and no IMAP IDLE equivalent. Nothing polls or holds a long-lived remote watch.

• Reconciles CalDAV credentials from SecretFabric into the service-owned encrypted cache (caldav-sync purpose), then decrypts only inside the service. CREDENTIAL_CACHE_KEY is required. There is no direct resolver fallback.

• Gates every real write behind event_preview → event_approval_create → event_write. The approval is payload-bound and lasts five minutes.

• On update, event_write loads the live ETag, sends it as If-Match, then reads the event back and checks UID, summary, and ETag.

Related MCP server: caldav-mcp

Safety model

• No secrets in MCP tools — account passwords never appear in tool arguments or JSON results.

• Active-account allowlist — only accounts registered via calendar_account_register (with an opaque secretRef) can be listed, read, or written.

• Human in the loop — creating or updating calendar events requires an explicit approval matching the exact iCal body.

• Remote failure — if CalDAV or the credential lease fails, calendar_list, event_search, event_read, and event_write return that error. They do not fill the result from SQLite. A missing remote event is event_not_found. An If-Match rejection is precondition_failed. A read-back that does not match the written UID, summary, or ETag fails the write.

Runtime configuration (required)

Local development

export AGENTCAL_DB_PATH=/tmp/agentcalendar.db
export AGENTCAL_SYNC_INTERVAL_SECONDS=300
export AGENTCAL_LOG_LEVEL=info
export AGENTCAL_TRANSPORT=stdio
export SECRET_FABRIC_URL=http://127.0.0.1:3000
export SECRET_FABRIC_API_TOKEN=your-token

yarn install
yarn check
yarn start

yarn start is the MCP stdio server. It does not start a sync loop.

Native host service

The supported process is Node on the host, started by tools/hermes-agentcalendar-mcp.sh or the systemd user template deploy/systemd/user/agentcalendar@.service. Both set AGENTCAL_SERVICE_MODE=native and the profile principal. They do not start a sync worker. Install steps are in docs/COMPOSE-TRANSITION.md. This repository does not ship a container image or Compose file.

export SECRET_FABRIC_URL=http://127.0.0.1:3000
export SECRET_FABRIC_API_TOKEN=your-token
export HERMES_HOME="$HOME/.hermes"
tools/hermes-agentcalendar-mcp.sh

Hermes MCP example

hermes mcp add agentcalendar -- /path/to/agentcalendar/tools/hermes-agentcalendar-mcp.sh

Register the native wrapper. It sets AGENTCAL_PRINCIPAL and SECRET_FABRIC_PRINCIPAL from HERMES_HOME. Empty SECRET_FABRIC_URL and SECRET_FABRIC_API_TOKEN values are loaded from ~/.config/agentcalendar/<profile>.env. Values already present in the environment are kept. The wrapper exits if either value is still missing and does not print secrets. CREDENTIAL_CACHE_KEY is a required external secret. The wrapper does not load it from the profile env file, so the MCP process environment must already contain it. The systemd user unit loads the whole env file.

MCP tools (summary)

• Accounts: calendar_account_list, calendar_account_status, calendar_account_register, calendar_account_deactivate — metadata and opaque refs, never credentials

• Calendars: calendar_list — live CalDAV list

• Sync status is inert: calendar_sync and calendar_sync_all report mode: remote-only, syncEnabled: false, and do not contact CalDAV

• Read: event_search and event_read query CalDAV directly. event_search reads one calendar, inside a time window (30 days before and after now when dates are omitted). The page size is 50 by default and 200 at most, ordered by date descending or ascending. A nextCursor is returned only when the CalDAV client honors a bounded calendar-query. If the window is larger than the page and the server cannot limit the REPORT, the tool returns pagination_unavailable and does not download every event body.

• Write (approval-gated): event_preview → event_approval_create → event_write

• Disabled local/queue tools return an error and do not mutate a mirror: event_update_local (remote_only_local_writes_disabled), event_upload_status and event_conflicts (remote_only_sync_disabled)

License

Apache-2.0