trilium-calendar-mcp
Provides tools for managing calendar events stored as Trilium notes via ETAPI, including listing calendars and events, creating, updating, deleting, and bulk-upserting events, and handling dates, times, recurrence, tags, locations, colors, and stable CalDAV UIDs.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@trilium-calendar-mcp create a meeting with Bob next Monday at 10am"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
trilium-calendar-mcp
Calendar events as MCP tools for AI agents, stored as notes in Trilium.
It is a drop-in replacement for the Nextcloud Calendar MCP (nc_calendar_*): the tool names and
arguments are deliberately the same shape (calendar_*), so an agent that already knows how to
write calendar events only needs the tool prefix changed — no relearning, no new prompt structure.
AI agent ──MCP──▶ trilium-calendar-mcp ──ETAPI──▶ Trilium notes
│
CalDAV facade ─────┘──▶ Apple Calendar / DAVx⁵ / ThunderbirdNotes carrying #startDate are calendar events in Trilium's own calendar view, and the same notes
can be served over CalDAV by a facade (see Interoperability), so one set of notes feeds the agent,
the Trilium UI and standard calendar clients.
Why not let the agent drive the Trilium MCP directly?
The generic Trilium MCP has no calendar semantics: creating one event means create_note plus one
set_attribute call per label, the agent has to know every label name, the inclusive-#endDate
convention and the timezone rules, and mistakes fail silently — a note labelled #startdate
simply never appears in the calendar, with no error. Those rules live in code here, and every event
is validated on the way in.
Related MCP server: caldav-mcp
Quickstart
docker run --rm -i \
-e TRILIUM_URL=https://trilium.example.com \
-e TRILIUM_ETAPI_TOKEN=your-etapi-token \
-e TRILIUM_CALENDARS=0hq1wCTuDBjA:Gaming \
ghcr.io/reinforcezwei/trilium-calendar-mcp:latestThat runs over stdio. For an HTTP (streamable) endpoint — what a remote agent infrastructure usually needs — add:
docker run --rm -p 127.0.0.1:8102:8102 \
-e MCP_TRANSPORT=streamable-http -e MCP_HOST=0.0.0.0 -e MCP_PORT=8102 \
-e TRILIUM_URL=https://trilium.example.com \
-e TRILIUM_ETAPI_TOKEN=your-etapi-token \
-e TRILIUM_CALENDARS=0hq1wCTuDBjA:Gaming \
ghcr.io/reinforcezwei/trilium-calendar-mcp:latest
# MCP endpoint: http://host:8102/mcpdocker-compose.yml wires the same thing up with an .env file.
HTTP and
Hostheaders. The MCP SDK rejects requests whoseHostheader is not allow-listed (DNS-rebinding protection,421 Invalid Host header) — a check whose SDK default depends on the bind address and has historically rejected every hostname in containers (python-sdk#1798). This server decides it explicitly instead, so no configuration is needed:
MCP_HOSTprotection
behaviour
0.0.0.0(container/VM default)off
any
Hostis accepted; the network/proxy is the boundary
127.0.0.1/localhoston
localhostand127.0.0.1names accepted — protects a loopback-only server from a browser on the same machineany bind +
MCP_ALLOWED_HOSTSon
only the listed
host:portvalues are acceptedThe startup log states which mode is active. Set
MCP_ALLOWED_HOSTS(and optionallyMCP_ALLOWED_ORIGINS) only when a loopback-bound server is reached under another name — e.g. a reverse proxy on the same host forwarding to127.0.0.1:8102.
Client configuration (stdio)
{
"mcpServers": {
"trilium-calendar": {
"command": "docker",
"args": ["run", "--rm", "-i", "--env-file", "/path/.env",
"ghcr.io/reinforcezwei/trilium-calendar-mcp:latest"]
}
}
}Configuration
Variable | Required | Default | Meaning |
| yes | — | Trilium base URL (no |
| yes | — | ETAPI token (Trilium → Options → ETAPI) |
| yes | — | Calendars to expose — see below |
| no |
| Timezone used to interpret naive datetimes |
| no |
|
|
| no |
| HTTP binding |
| no | — | Optional |
| no | derived | Optional |
| no |
| Set |
| no | — | Custom CA bundle path |
| no |
| Per-request timeout (seconds) |
| no |
| Max notes fetched per calendar scan |
| no |
| Log verbosity (logs go to stderr) |
Calendars and their names
TRILIUM_CALENDARS is a comma-separated list of Trilium note ids, each optionally named:
TRILIUM_CALENDARS=0hq1wCTuDBjA:Gaming,kf8Xq2vLpZ1a:Personal
# or, without aliases (the note's own title is then used as the name)
TRILIUM_CALENDARS=0hq1wCTuDBjA,kf8Xq2vLpZ1aThe name after the colon (or
=) is thecalendar_namethe agent uses. Without an alias the calendar note's Trilium title is used instead, so "Gaming" works either way once the note is titled that.calendar_list_calendarsreturns every calendar withname,note_id,title,timezone,colorandevent_count— that is how the agent resolves "put it in Gaming".All tools accept
calendar_name; it matches the name/alias, the note title, or the note id, case-insensitively. The first configured calendar is the default whencalendar_nameis omitted.An unknown name is an error that lists the valid ones, so the agent can self-correct.
Tools
Tool | Purpose |
| List calendars with their names/ids/timezones — call this first |
| Events in a date range; filters on title, categories, location |
| One event by uid, including description |
| Create an event (returns its uid) |
| Patch an event; only the arguments you pass change |
| Delete by uid (unknown uid = success, safe retries) |
| Events starting in the next N days |
| Bulk create-or-update, keyed on uid |
| Bulk delete by uid |
Migrating an agent from the Nextcloud MCP
Rename the tool prefix; arguments keep their names:
Nextcloud MCP | this server |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
Point the prompt's calendar name at a configured name (e.g. Gaming) and the switch is done.
calendar_create_event also accepts event_uid: pass an existing uid to update instead of
creating a duplicate, which makes unattended re-runs idempotent.
Semantics the agent can rely on
Dates —
start_datetimetakesYYYY-MM-DD(all-day) or an ISO datetime. Naive datetimes are read in thetimezoneargument, else the calendar's timezone;Z/offset values are converted. Either way, what is stored is the wall clock in the calendar's timezone.All-day ranges —
end_datetimeis the last day of the event, inclusive ("until the 28th" means the 28th). This differs from Nextcloud'sDTEND, which is the day after: a Nextcloud all-day event ending2026-07-28covered 7/8–7/27. Re-check any all-day ranges in the old prompt when you migrate.Times — timed events get
#startTime/#endTime; an event with no end time is open-ended.Identity — every event carries a stable
#caldavUID. New events get a UUID; passevent_uid(or usecalendar_upsert_events) to update in place.Descriptions — plain text, line breaks preserved. Markdown syntax is not interpreted.
Response fields — every response reflects what is actually stored. An update that does not include
descriptionreturns the stored body (never an empty string), so it is safe to trust the response instead of re-fetching.End fields —
endis the ISO end (ornullwhen a timed event has no end time), andend_dateis the event's last day whenever it has an end. For a same-day timed event (15:00–15:30)end_dateis therefore that same day, notnull. Note that the#endDatelabel is only written when an event spans days (Trilium's convention, which the CalDAV facade understands), so if you inspect the notes directly, expect fewer labels than response fields.Not stored —
status,priority,privacy,attendees,url, reminders/alarms. These arguments are accepted so an existing prompt does not break, and echoed back inignored_fieldsso the agent can see they had no effect.Recurrence — pass an RRULE in
recurrence_rule(FREQ=WEEKLY;BYDAY=MO), optionally bounded withrecurrence_end_date;recurring=Falseorrecurrence_rule=""removes it.
How events are stored
Trilium label | Meaning |
|
|
| last day, inclusive |
|
|
| stable identity / idempotency key |
| categories, comma-separated |
| passthrough fields |
Notes are created as normal Trilium text notes with the event description as their body, so they read naturally in the note tree and the calendar view.
Interoperability with a CalDAV facade
The labels above match the mapping used by the Trilium CalDAV facade
(#endDate inclusive → DTEND +1 day, #caldavUID → UID, #tags → CATEGORIES), so events
written by an agent are served correctly to Apple Calendar, DAVx⁵ and Thunderbird by the same
facade. Nothing here requires the facade, and the facade does not require this server.
Limitations
No reminders/alarms, attendees, or event status — Trilium notes have no equivalent.
No todos/VTODO — event notes only (Trilium's
#todoDatetask notes are a follow-up).Timezones are per calendar, not per event — a single calendar has one timezone; events from several zones are normalised into it.
Listing scans the calendar's children (one ETAPI search) and filters locally; fine for the thousands-of-events scale, not for millions.
No ETags/conflict detection — last write wins, which is fine for an agent-owned calendar.
Development
python -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"
pytest tests/test_event.py # unit tests, no server needed
TRILIUM_URL=https://... TRILIUM_ETAPI_TOKEN=... pytest # + integration tests against a live instanceIntegration tests create a temporary calendar note under root, exercise create/list/update/
upsert/delete against it, and delete it afterwards (cascading to the events they made). No existing
notes are touched.
Releasing
./release.sh 0.2.0 # bump version, commit, tag
./release.sh 0.2.0 --push # ... and push the commit + tagPushing a v* tag runs the test suite, then builds and publishes
ghcr.io/<owner>/trilium-calendar-mcp (0.2.0, 0.2, latest) for linux/amd64 and
linux/arm64, and opens a GitHub release.
License
MIT
Available Tools
9 toolscalendar_create_eventA
Create a calendar event.
Args:
title: Event title.
start_datetime: YYYY-MM-DD for an all-day event, or an ISO datetime
such as 2026-07-08T11:00:00 (naive = calendar timezone) /
2026-07-08T03:00:00Z (converted to calendar timezone).
calendar_name: Calendar to create in; omit for the default calendar.
end_datetime: ISO datetime end, or for all-day events the LAST day
(inclusive). Empty = same day / no end.
all_day: Force an all-day event (times are ignored).
description: Plain text; line breaks are preserved.
location: Free text location.
categories: Comma-separated categories/tags.
timezone: IANA timezone used to interpret naive datetimes.
color: Colour name or hex.
recurrence_rule: RRULE body, with or without the RRULE: prefix.
recurrence_end_date: YYYY-MM-DD that bounds the series (writes UNTIL).
recurring: Set False to force a non-recurring event.
event_uid: Reuse an existing uid (updates that event instead of
creating a duplicate) — use it to make retries idempotent.
status, priority, privacy, attendees, url, reminder_minutes,
reminder_email, reminders: accepted for compatibility but NOT stored
by Trilium; they are echoed back in ignored_fields.
Inputs: title (required), start_datetime (required), url, color, +18 more.
calendar_delete_eventB
Delete an event by uid. Deleting an unknown uid succeeds (safe retries).
Args: event_uid: Uid of the event to delete. calendar_name: Calendar holding the event; omit to search all calendars.
Inputs: event_uid (required), calendar_name.
calendar_delete_eventsA
Delete many events by uid in one call.
Args: event_uids: Uids to delete; unknown uids are reported, not an error. calendar_name: Calendar to delete from; omit to search all calendars.
Inputs: event_uids (required), calendar_name.
calendar_get_eventA
Get one event by its uid, including its description.
Args:
calendar_name: Calendar to look in; omit to search all calendars.
event_uid: The event's uid (from calendar_list_events).
Inputs: event_uid, calendar_name.
calendar_get_upcoming_eventsB
List events starting between today and N days ahead.
Args: calendar_name: Calendar to read; omit for all calendars. days_ahead: How many days ahead to include (today counts as day 0). limit: Maximum number of events to return.
Inputs: limit, days_ahead, calendar_name.
calendar_list_calendarsA
List the calendars this server exposes.
Returns each calendar's name (use this as calendar_name in other
tools), its Trilium note_id, note title, timezone, colour and the
current number of events. Start here: calendar names are how the user
refers to calendars (e.g. "Gaming"), and they are what the other tools
accept.
Inputs: no named parameters.
calendar_list_eventsA
List events, optionally filtered by date range and text.
Args:
calendar_name: Calendar to read; omit to use the default calendar.
start_date: Earliest day to return, YYYY-MM-DD (events overlapping
the range are included).
end_date: Latest day to return, YYYY-MM-DD.
limit: Maximum number of events to return (0 = no limit).
title_contains: Only events whose title contains this text.
categories: Comma-separated categories; matches events carrying any of them.
location_contains: Only events whose location contains this text.
include_descriptions: Fetch event bodies (one extra request per event).
search_all_calendars: Search every configured calendar instead of one.
Inputs: limit, end_date, categories, start_date, +5 more.
calendar_update_eventA
Update an existing event. Only the arguments you pass are changed.
The returned event reflects what is now stored: if you do not pass
description, the response carries the existing body (not an empty
string), so you do not need to re-fetch to confirm it survived.
Args:
event_uid: Uid of the event to update.
calendar_name: Calendar holding the event; omit to search all calendars.
(other arguments as in calendar_create_event; end_datetime="" clears
the end, location="" clears the location, recurrence_rule="" or
recurring=False removes the recurrence.)
Inputs: event_uid (required), color, title, all_day, +10 more.
calendar_upsert_eventsA
Create or update many events at once, keyed on uid (or on key).
Use this for bulk work (a release calendar for a whole season). Each
entry is created if its identity is new and updated if it already
exists, so re-running the same list updates in place instead of
duplicating. Identity comes from event_uid/uid, or from key: a
short stable slug ("wuwa-3.7-banner-1") that is hashed into a uid, so
a scheduled agent can re-publish its list without storing uids.
Args:
events: List of event objects. Each accepts the arguments of
calendar_create_event (title, start_datetime, end_datetime,
all_day, description, location, categories, color,
recurrence_rule) plus the identity fields event_uid/uid or
key. calendar_name may be set per entry to spread the list
across calendars. Entries with no identity always create new
events.
calendar_name: Default calendar for entries that do not name one.
Inputs: events (required), calendar_name.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Most tools have clearly distinct actions (list, get, create, update, delete, upcoming, bulk upsert/delete). Slight overlap exists between calendar_get_upcoming_events and calendar_list_events with a date range, and between calendar_create_event's event_uid idempotency and calendar_upsert_events, but descriptions clarify the intended distinctions.
All nine tools follow a consistent calendar_verb_noun pattern with snake_case throughout. Verb choices (list, get, create, update, delete, upsert) are predictable and parallel, including the plural bulk variants.
Nine tools is well-scoped for a calendar server, covering single-event CRUD plus bulk operations and an upcoming shortcut without redundancy. Each tool earns its place.
Full CRUD lifecycle is covered (list, get, create, update, delete) plus bulk upsert/delete, upcoming events, and recurrence support. No obvious calendar operations are missing.
Maintenance
Related MCP Connectors
Calendar API for AI agents: events, availability, Google/Microsoft setup, scheduling, and iCal.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
Read and manage To-do Calendar todos, schedules and tags from an AI agent.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Related MCP Servers
- FlicenseNot gradedqualityCmaintenanceEnables LLM agents to read, schedule, update, and delete calendar events and tasks on a self-hosted CalDAV server, and to query availability for free/busy slots.1-
- AlicenseNot gradedqualityAmaintenanceConnects AI assistants to CalDAV servers so they can list calendars and browse, create, update, or delete events and to-do tasks within a chosen timeframe. Supports scheduling of recurring and all-day events, task filtering and pagination, and completion tracking through natural language.732 npmMIT
- AlicenseNot gradedqualityAmaintenanceEnables AI assistants to connect to CalDAV servers and manage calendars, events, and tasks through tools for listing, creating, updating, completing, and deleting items.732 npmMIT
- AlicenseNot gradedqualityAmaintenanceConnects AI assistants to CalDAV servers so they can list calendars, browse events within a timeframe, and create, update, delete, or complete events and tasks (VTODOs) through natural language. Supports recurring events, all-day entries, and todo filtering by status or due date with pagination.732 npmMIT