Overview

The Kalendis MCP Server is a Model Context Protocol (MCP) tool that exposes Kalendis scheduling API functionality as reusable tools for AI agents and generates TypeScript clients and server route scaffolding. It streamlines integrating availability, recurring availability, exceptions, bookings, and account operations into frontend and backend projects by producing type-safe clients and ready-to-drop API route handlers for popular frameworks.

For developers building scheduling features — from simple availability lookups to complex booking flows — this tool reduces boilerplate, enforces consistent authentication, and provides strong TypeScript typings so you can call Kalendis endpoints with confidence.

Features

MCP server that exposes Kalendis API tools for AI assistants (Claude, Cursor, etc.)
TypeScript client generator for backend and frontend usage
API route generator scaffolding for Next.js (App Router), Express, Fastify, and NestJS
Full TypeScript typings for all Kalendis endpoints
Environment-driven configuration for sandbox and production endpoints
Secure API key management via environment variables
Tooling to list available endpoints and generate custom code per project

Installation / Configuration

Install the package via npm:

npm install @kalendis/mcp

Add the MCP server to your MCP configuration (example):

{
  "mcpServers": {
    "kalendis": {
      "command": "npx",
      "args": ["-y", "@kalendis/mcp"]
    }
  }
}

Environment config — supported hosts:

# development
KALENDIS_BASE_URL=https://sandbox.api.kalendis.dev
# production
# KALENDIS_BASE_URL=https://api.kalendis.dev

# API key used by generated clients
KALENDIS_API_KEY=sk_XXXXXXXXXXXX

Authentication: all requests to Kalendis require the x-api-key header. Generated clients accept an apiKey option and will set this header automatically.

Available Tools

The MCP server exposes a set of tools (actions) you can call programmatically or via an AI agent:

generate-backend-client — produces a TypeScript client that calls Kalendis API directly
generate-frontend-client — produces a client that calls your backend endpoints
generate-api-routes — scaffolds API routes for Next.js, Express, Fastify, or NestJS
list-endpoints — lists supported Kalendis API endpoints and schemas

Quick examples

Backend client usage (generated):

import KalendisClient from './generated/kalendis-client';

const client = new KalendisClient({
  apiKey: process.env.KALENDIS_API_KEY,
  baseUrl: process.env.KALENDIS_BASE_URL,
});

const users = await client.getUsers();
const booking = await client.createBooking({ userId: 'u_123', start: '2026-05-01T10:00:00Z' });

Frontend client (calls your backend):

import api from './generated/frontend-client';

// Calls your backend proxy endpoints like /api/kalendis/users
const users = await api.getUsers();

Next.js (App Router) route example:

// app/api/kalendis/users/route.ts
import { NextResponse } from 'next/server';
import KalendisClient from '../../../generated/kalendis-client';

const client = new KalendisClient({ apiKey: process.env.KALENDIS_API_KEY });

export async function GET() {
  const users = await client.getUsers();
  return NextResponse.json(users);
}

Express route example:

// routes/kalendis.ts
import express from 'express';
import KalendisClient from '../generated/kalendis-client';

const router = express.Router();
const client = new KalendisClient({ apiKey: process.env.KALENDIS_API_KEY });

router.get('/api/users', async (req, res, next) => {
  try {
    const users = await client.getUsers();
    res.json(users);
  } catch (err) {
    next(err);
  }
});

export default router;

Fastify route example:

// routes/kalendis.ts
export default async function routes(fastify) {
  const client = new fastify.kalendisClient; // or initialize normally
  fastify.get('/api/availability', async (request, reply) => {
    return client.getAvailability(request.query);
  });
}

Use Cases

Build a scheduling UI that queries calculated availability and creates bookings without writing repetitive network code.
Generate a secure backend client for server-side operations (webhooks, batch syncs, admin tooling).
Scaffold API routes for serverless deployments (Next.js App Router) to keep your frontend free of direct Kalendis keys.
Let an AI agent use Kalendis tools (via MCP) to automate availability checks, suggest meeting slots, or provision bookings programmatically.
Integrate with NestJS or Fastify backends quickly with generated controllers and services that wrap Kalendis calls.

API Coverage & Resources

The generator covers all Kalendis endpoints for users, availability, recurring availability, availability exceptions, bookings, and account management. Use the list-endpoints tool to fetch the full endpoint list and JSON schemas before generating clients or routes.

Repository: https://github.com/kalendis-dev/kalendis-mcp

If you need further examples for a specific framework or to customize generated types and route handlers, consult the repository README and the generated code as a starting point.

Kalendis MCP Server: TypeScript Clients & API Routes