Skip to main content
Glama
trilium-calendar-mcp

trilium-calendar-mcp

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⁵ / Thunderbird

Notes 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:latest

That 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/mcp

docker-compose.yml wires the same thing up with an .env file.

HTTP and Host headers. The MCP SDK rejects requests whose Host header 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_HOST

protection

behaviour

0.0.0.0 (container/VM default)

off

any Host is accepted; the network/proxy is the boundary

127.0.0.1 / localhost

on

localhost and 127.0.0.1 names accepted — protects a loopback-only server from a browser on the same machine

any bind + MCP_ALLOWED_HOSTS

on

only the listed host:port values are accepted

The startup log states which mode is active. Set MCP_ALLOWED_HOSTS (and optionally MCP_ALLOWED_ORIGINS) only when a loopback-bound server is reached under another name — e.g. a reverse proxy on the same host forwarding to 127.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

TRILIUM_URL

yes

—

Trilium base URL (no /etapi suffix)

TRILIUM_ETAPI_TOKEN

yes

—

ETAPI token (Trilium → Options → ETAPI)

TRILIUM_CALENDARS

yes

—

Calendars to expose — see below

TRILIUM_TIMEZONE

no

Asia/Shanghai

Timezone used to interpret naive datetimes

MCP_TRANSPORT

no

stdio

stdio, streamable-http (alias http) or sse

MCP_HOST / MCP_PORT / MCP_PATH

no

0.0.0.0 / 8102 / /mcp

HTTP binding

MCP_ALLOWED_HOSTS

no

—

Optional host:port allowlist; enables the DNS-rebinding check for binds where it is otherwise off (see the note above)

MCP_ALLOWED_ORIGINS

no

derived

Optional Origin allowlist to accompany MCP_ALLOWED_HOSTS

TRILIUM_VERIFY_SSL

no

true

Set false for a self-signed instance

TRILIUM_CA_BUNDLE

no

—

Custom CA bundle path

TRILIUM_TIMEOUT

no

30

Per-request timeout (seconds)

TRILIUM_SEARCH_LIMIT

no

5000

Max notes fetched per calendar scan

LOG_LEVEL

no

INFO

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,kf8Xq2vLpZ1a
  • The name after the colon (or =) is the calendar_name the 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_calendars returns every calendar with name, note_id, title, timezone, color and event_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 when calendar_name is omitted.

  • An unknown name is an error that lists the valid ones, so the agent can self-correct.

Tools

Tool

Purpose

calendar_list_calendars

List calendars with their names/ids/timezones — call this first

calendar_list_events

Events in a date range; filters on title, categories, location

calendar_get_event

One event by uid, including description

calendar_create_event

Create an event (returns its uid)

calendar_update_event

Patch an event; only the arguments you pass change

calendar_delete_event

Delete by uid (unknown uid = success, safe retries)

calendar_get_upcoming_events

Events starting in the next N days

calendar_upsert_events

Bulk create-or-update, keyed on uid

calendar_delete_events

Bulk delete by uid

Migrating an agent from the Nextcloud MCP

Rename the tool prefix; arguments keep their names:

Nextcloud MCP

this server

nc_calendar_list_calendars

calendar_list_calendars

nc_calendar_list_events

calendar_list_events

nc_calendar_get_event

calendar_get_event

nc_calendar_create_event

calendar_create_event

nc_calendar_update_event

calendar_update_event

nc_calendar_delete_event

calendar_delete_event

nc_calendar_get_upcoming_events

calendar_get_upcoming_events

nc_calendar_bulk_operations

calendar_upsert_events / calendar_delete_events

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_datetime takes YYYY-MM-DD (all-day) or an ISO datetime. Naive datetimes are read in the timezone argument, 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_datetime is the last day of the event, inclusive ("until the 28th" means the 28th). This differs from Nextcloud's DTEND, which is the day after: a Nextcloud all-day event ending 2026-07-28 covered 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; pass event_uid (or use calendar_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 description returns the stored body (never an empty string), so it is safe to trust the response instead of re-fetching.

  • End fields — end is the ISO end (or null when a timed event has no end time), and end_date is the event's last day whenever it has an end. For a same-day timed event (15:00–15:30) end_date is therefore that same day, not null. Note that the #endDate label 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 in ignored_fields so the agent can see they had no effect.

  • Recurrence — pass an RRULE in recurrence_rule (FREQ=WEEKLY;BYDAY=MO), optionally bounded with recurrence_end_date; recurring=False or recurrence_rule="" removes it.

How events are stored

Trilium label

Meaning

#startDate

YYYY-MM-DD, always present (this is what makes it an event)

#endDate

last day, inclusive

#startTime / #endTime

HH:MM, timed events only, naive wall clock

#caldavUID

stable identity / idempotency key

#tags

categories, comma-separated

#location, #color, #recurrence

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 #todoDate task 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 instance

Integration 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 + tag

Pushing 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 tools
calendar_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

    A4/5.0

    Scored across 9 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      A
      maintenance
      Connects 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 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables AI assistants to connect to CalDAV servers and manage calendars, events, and tasks through tools for listing, creating, updating, completing, and deleting items.
      732 npm
      MIT
    • A
      license
      Not graded
      quality
      A
      maintenance
      Connects 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 npm
      MIT