npm package: @kalendme/mcp-server
Description: KalendMe MCP server — use KalendMe scheduling as a native tool in Claude, Cursor, and other AI clients
Latest version: 0.1.0

# KalendMe MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that exposes the KalendMe REST API as tools for AI assistants — Claude Desktop, Cursor, Windsurf, and any other MCP-compatible client.

## What it does

Your AI assistant can:

- **Check availability** — find open slots on any booking link
- **Book sessions** — create bookings on behalf of guests
- **Block time** — prevent bookings during a window
- **Cancel events** — cancel a calendar event with optional guest notification
- **Manage booking links** — list, get, create, and update scheduling links
- **List users** — browse your organization's members
- **Manage webhooks** — register, list, and delete webhook endpoints

## Prerequisites

- Node.js 18+
- A KalendMe API key — generate one at **Settings → API Keys** in your KalendMe dashboard

## Setup

### Claude Desktop

1. Open `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows).
2. Add the server under `mcpServers`:

```json
{
  "mcpServers": {
    "kalendme": {
      "command": "npx",
      "args": ["-y", "kalendme-mcp"],
      "env": {
        "KALENDME_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

3. Restart Claude Desktop.

### Cursor

Open **Settings → MCP** and add:

```json
{
  "kalendme": {
    "command": "npx",
    "args": ["-y", "kalendme-mcp"],
    "env": {
      "KALENDME_API_KEY": "your_api_key_here"
    }
  }
}
```

### Running from source (development)

```bash
# From the repo root
pnpm --filter @kalendme/mcp-server build

# Then configure your client to run:
KALENDME_API_KEY=your_key node apps/mcp-server/dist/index.js
```

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `KALENDME_API_KEY` | ✅ | — | Your KalendMe API key |
| `KALENDME_BASE_URL` | ❌ | `https://app.kalendme.com` | Override for self-hosted or staging |

## Available tools

### Availability

| Tool | Description |
|---|---|
| `check_availability` | Get open booking slots for a user + link within a date range |
| `get_mass_availability` | Find times when multiple users are all free *(Premium)* |

### Calendar Events

| Tool | Description |
|---|---|
| `get_calendar_events` | Fetch a user's calendar events with optional date range filter |
| `book_session` | Book a session through the public booking flow |
| `block_time` | Block time on a user's calendar to prevent bookings |
| `cancel_calendar_event` | Cancel an event, optionally notifying the guest |

### Booking Links

| Tool | Description |
|---|---|
| `list_scheduling_links` | List all booking links for a user |
| `get_scheduling_link` | Get full details of a specific link |
| `create_scheduling_link` | Create a new booking link |
| `update_scheduling_link` | Update an existing link's settings |

### Users

| Tool | Description |
|---|---|
| `list_organization_users` | List all users in the organization |

### Webhooks

| Tool | Description |
|---|---|
| `create_webhook` | Register a webhook endpoint for real-time event notifications |
| `list_webhooks` | List all registered webhooks |
| `delete_webhook` | Delete a webhook registration |

## Error handling

- **401** — invalid or missing API key
- **402** — feature requires a Premium plan (includes upgrade link)
- **404** — resource not found
- **409** — booking conflict (host unavailable)
- **422** — invalid input (Zod validation details included)

## Transport

stdio — the server communicates over stdin/stdout, which is the standard transport for local MCP integrations.