afwlehmann/mcp-khal

An MCP server that lets an assistant read and create events in your khal calendars.
## Tools
| Tool | Purpose | Parameters |
| listcalendars | List the configured calendars | — |
| listevents | List events in a date range (default: today + 7 days) | range?, calendar? |
| eventsinrange | List all events intersecting a time range | start, end, calendar? |
| searchevents | Search events by text | query, calendar? |
| newevent | Create an event or a recurring series | start, end?, summary, calendar?, location?, description?, alarm?, recurrence?, attendees?, organizer? |
newevent is the only tool that writes. Its description tells the calling agent to ask the user for confirmation first, and never to invite attendees without explicit approval. The other tools are read-only and also work on read-only calendars.
### Recurring events
recurrence is { pattern, ending? }. For a series, start must be YYYY-MM-DD HH:MM (the first occurrence, which must match the pattern), end is a required HH:MM, and times are local.
pattern is one of:
{ "kind": "daily", "interval"?: n }
{ "kind": "weekly", "interval"?: n, "weekdays": [...] }
{ "kind": "monthlyday", "interval"?: n, "day": 1-31 }
{ "kind": "monthlyweekday", "interval"?: n, "nth": 1-4 | -1, "weekday": "..." }
{ "kind": "yearly", "interval"?: n }
ending is { "kind": "never" }, { "kind": "count", "count": n } or { "kind": "until", "date": "YYYY-MM-DD" }.
Example, every 2nd Wednesday of the month: { "pattern": { "kind": "monthlyweekday", "nth": 2, "weekday": "wednesday" } }.
### Invites
With attendees (email addresses), newevent imports an ICS with ORGANIZER and one ATTENDEE per address. Like a series, start must be YYYY-MM-DD HH:MM and end an HH:MM. The organizer is organizer if given, else the calendar's entry from the setup mapping, else the calendar name if it is an email address; otherwise the call fails. khal does not send the invites; that is left to your sync/mail tooling.
## Usage
npm install && npm run build
MCP client config:
json
{ "mcpServers": { "khal": { "command": "node", "args": ["/path/to/mcp-khal/dist/cli.js"] } } }
## Nix / Home Manager
The flake exposes:
| Output | Purpose |
| packages. .default | The server. The version is taken from package.json and khal is bundled on its PATH. |
| overlays.default | Adds pkgs.mcp-khal. |
| homeModules.default | The Home Manager module programs.mcp-khal. |
### Home Manager module
Add the flake as an input, import the module and enable it:
nix
# flake.nix of your Home Manager configuration
inputs.mcp-khal.url = "github: /mcp-khal";
# home configuration
{ config, inputs, ... }:
imports = [ inputs.mcp-khal.homeModules.default ];
programs.mcp-khal = {
enable = true;
# calendar name -> your email address on that calendar
calendarEmails = {
work = "me@example.com";
private = "me@example.org";
};
};
Options:
| Option | Type | Default | Description |
| programs.mcp-khal.enable | bool | false | Install mcp-khal into home.packages. |
| programs.mcp-khal.package | package | the flake's default package for your system | Override to use your own build or an overlay. |
| programs.mcp-khal.calendarEmails | attrs of email address | { } | Calendar name → your address on it. Used as the organizer of invites (see Invites). Values are validated with the same rule as the server, so a typo fails at home-manager switch instead of breaking invites later. |