# Install the Kalendia MCP server

Kalendia (https://kalendia.io) is cross-account calendar sync and scheduling. This MCP server lets an
AI agent drive a user's Kalendia account from chat: list connected calendars, read an agenda, and
create / run / delete calendar sync rules and scheduling pages.

## You are an AI agent? Set this up automatically.

Do the following for your user. The ONLY thing the user does by hand is paste a token (step 2).

### 1. Ensure uv is installed

`uvx` (from uv) runs the server with no separate install. Check `uv --version`. If missing, install:

- macOS / Linux: `curl -LsSf https://astral.sh/uv/install.sh | sh`
- Homebrew: `brew install uv`
- Windows: `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"`

### 2. Get the user's Kalendia token (the only manual step)

Ask the user to open https://kalendia.io/dashboard/settings -> API tokens -> Create a token, then paste the `kld_...`
value back to you. It is shown once. (No Kalendia account yet? They sign up free at https://kalendia.io.)

### 3. Register the MCP server

Use the user's token as KALENDIA_TOKEN.

Claude Code (one command):

```bash
claude mcp add kalendia \
  -e KALENDIA_TOKEN=PASTE_YOUR_TOKEN \
  -e KALENDIA_API_URL=https://api.kalendia.io \
  -- uvx --from git+https://github.com/bradbogdan/kalendia-mcp.git kalendia-mcp
```

Any other MCP client (Cursor, Claude Desktop, VS Code, Windsurf, ...) — add to its mcpServers config:

```json
{
  "mcpServers": {
    "kalendia": {
      "command": "uvx",
      "args": ["--from","git+https://github.com/bradbogdan/kalendia-mcp.git","kalendia-mcp"],
      "env": {
        "KALENDIA_TOKEN": "PASTE_YOUR_TOKEN",
        "KALENDIA_API_URL": "https://api.kalendia.io"
      }
    }
  }
}
```

### 4. Verify

Restart the client so it loads the server, then call the `list_connections` tool. A successful
response (the user's connected calendar accounts) confirms the token works. If you get an auth error,
the token is wrong or revoked — repeat step 2.

## Tools the server exposes

- Read: list_connections, list_calendars, list_all_calendars, list_sync_rules, get_agenda, list_scheduling_pages, get_scheduling_page, get_availability, get_billing, get_billing_overview, get_audit_log
- Sync rules: create_sync_rule, run_sync_rule, delete_sync_rule
- Connections and calendars: connect_icloud, connect_ics, refresh_calendars, discover_calendars, set_active_calendars, rename_calendar, disconnect_connection
- Scheduling pages: create_scheduling_page, update_scheduling_page, delete_scheduling_page

Read tools are annotated read-only; deletes and disconnect are marked destructive, so a well-behaved
client confirms with the user before running them.

## Notes

- A Kalendia token grants the user's full account access (no scopes yet). Treat it like a password.
  The user can revoke any token at https://kalendia.io/dashboard/settings.
- KALENDIA_API_URL must be https://api.kalendia.io.
- Source: https://github.com/bradbogdan/kalendia-mcp