mcpField
J
jmap-calendar-mcp

jmap-calendar-mcp

Local
github.com/robertdoneillProductivity0Updated 1w ago
Repository

About jmap-calendar-mcp

jmap-calendar-mcp is a Python MCP server for viewing and managing calendars on JMAP servers that support JMAP for Calendars, including Stalwart 1.0 and later. It is designed for agent use, with deletion and invitation sending disabled by default.

Key features

  1. 01List calendars and default calendar
  2. 02Find events by time range and text
  3. 03Create and update events
  4. 04Expand recurring events in searches
  5. 05Opt-in deletion and invitations

Use cases

  1. 01Review upcoming calendar events
  2. 02Schedule or reschedule meetings
  3. 03Search recurring events across a date range
  4. 04Allow controlled calendar changes by an agent

MCP support

The server exposes calendar listing, search, creation, update, and optionally deletion tools to MCP clients. It connects to a configured JMAP session using a bearer token.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "robertdoneill-jmap-calendar": {
      "command": "uvx",
      "args": [
        "jmap-calendar-mcp"
      ],
      "env": {
        "JMAP_SESSION_URL": "<JMAP_SESSION_URL>",
        "JMAP_BEARER_TOKEN": "<JMAP_BEARER_TOKEN>",
        "JMAP_ALLOW_INVITES": "<JMAP_ALLOW_INVITES>",
        "JMAP_ALLOW_DELETE": "<JMAP_ALLOW_DELETE>"
      }
    }
  }
}
Run commanduvx jmap-calendar-mcp
Environment variables to set
JMAP_SESSION_URLJMAP session URL, usually https://<host>/.well-known/jmap
JMAP_BEARER_TOKENSecretAPI key for the account, limited to calendar permissions
JMAP_ALLOW_INVITES1 to allow sending invitations when a call asks for it
JMAP_ALLOW_DELETE1 to offer delete_calendar_event

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
pypijmap-calendar-mcp0.2.0

Tools

4

Saved tool list · updated 1w ago

This tool takes no parameters.

Details

From the project README

jmap-calendar-mcp

An MCP server that lets an AI agent see your calendars, find events, and create, change or (if you allow it) delete events on any JMAP server that supports JMAP for Calendars, such as Stalwart 1.0 and later.

One Python file, standard library only.

Tools

ToolWhat it does
list_calendarsCalendars on the account, and which one is the default
find_calendar_eventsEvents in a time range (default: the next 30 days), optionally matching text; recurring events are expanded
create_calendar_eventNew event: title, start, time zone, length or all-day, description, location, attendees
update_calendar_eventChange only the given fields of an existing event, or move it to another calendar
delete_calendar_eventDelete an event, every occurrence if it repeats. Only offered with JMAP_ALLOW_DELETE=1

Built to be safe to hand to an agent:

  • No delete by default. An agent can move or rename an event but cannot remove one. Set JMAP_ALLOW_DELETE=1 to offer delete_calendar_event; it sends no cancellations.
  • No invitations by default. Attendees are added without being emailed. Sending invitations needs both JMAP_ALLOW_INVITES=1 on the server and send_invitations: true on the call.
  • Use a key with calendar permissions only, so the agent cannot read or send mail through it.

Setup

  1. Create an API key for the account. On Stalwart, open the account in the admin (Directory → Accounts), set the key's permissions to Replace all permissions, and give it only these:

    • Sign in to the server
    • JMAP: Retrieve calendar details and properties
    • JMAP: Track changes to calendars since a given state
    • JMAP: Retrieve calendar event details
    • JMAP: Track changes to calendar events since a given state
    • JMAP: Search for calendar events matching criteria
    • JMAP: Track changes to calendar event query results
    • JMAP: Create new calendar events
    • JMAP: Modify existing calendar events
    • JMAP: Remove calendar events (only if you set JMAP_ALLOW_DELETE=1)

    The key then cannot read or send mail.

  2. Add the server to your MCP client. For Claude Code:

claude mcp add calendar \
  -e JMAP_SESSION_URL=https://mail.example.com/.well-known/jmap \
  -e JMAP_BEARER_TOKEN=your-api-key \
  -- uvx jmap-calendar-mcp

For several accounts, add one server per account (calendar-work, calendar-home).

VariableMeaning
JMAP_SESSION_URLThe server's JMAP session URL, usually https://<host>/.well-known/jmap
JMAP_BEARER_TOKENAPI key for the account
JMAP_ALLOW_INVITES1 to allow sending invitations when a call asks for it; off by default
JMAP_ALLOW_DELETE1 to offer delete_calendar_event; off by default

Keep the key out of shell history and config files where you can: load it from your password manager or secret store when the server starts.

License

MIT

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.