Skip to main content
Glama
Slotlock

Slotlock

Official
by PILOTAAI

Slotlock

Slotlock is a calendar for AI agents. It books vehicles, rooms, machines, people or anything else reservable, answers "when is this free?" from weekly availability rules, and lets PostgreSQL reject double bookings, however many writers race. Agents call it over MCP or A2A; your code calls it as a TypeScript library.

Why it is built for agents

  • Resources own calendars, not users, and the tenant comes only from the authenticated caller.

  • Intervals are half-open [start, end), so back-to-back bookings never collide.

  • A PostgreSQL exclusion constraint decides overlaps; a conflict comes back as data, not an error.

  • Writes are idempotent and take an expected revision.

  • Free/busy says whether it is certain: a calendar not yet synced makes time unproven, not free.

  • Tool names, schemas and errors work on Claude, OpenAI and every MCP host.

Related MCP server: restaurant-mcp

Get started

The documentation is at slotlock.pylota.io/docs, with a page each for the booking MCP server, the booking API, use cases and pricing. There are three ways to run Slotlock:

  • Slotlock Cloud: nothing to run. Sign in with GitHub or Google at https://app.slotlock.pylota.io/dashboard, create a key, and connect an agent to https://slotlock-api.pylota.io/mcp. Start on Free, with no card; Developer and Team add room for agents in production (pricing). Best effort, with no service level agreement.

  • Self-host with Docker, or from npm with Self-hosting.

  • As a TypeScript library inside your own Node.js service.

Self-host with Docker

From a clone of this repository:

scripts/quickstart-env.sh > .env    # .env.example, its four secrets set to openssl rand -hex 32
docker compose up --build --detach
docker compose exec slotlock slotlock resource add vehicle-42 --timezone Europe/London

URL

What

http://localhost:8080/mcp

MCP, with Authorization: Bearer <SLOTLOCK_AUTH_TOKEN>

http://localhost:8080/a2a

A2A 1.0, same token; card at /.well-known/agent-card.json

http://localhost:8080/v1/…

REST: the tools, and the application API for admin keys; described at /openapi.json

http://localhost:8080/healthz

Readiness, including the database

http://localhost:8080/metrics

Prometheus metrics, with Authorization: Bearer <SLOTLOCK_METRICS_TOKEN>; off without it

The server listens on 127.0.0.1:8080, as a database role that cannot bypass row-level security. .env.example makes every resource bookable on weekdays 09:00 to 17:00 and every write wait for a person. The Quickstart walks through it with Claude Code; Self-hosting covers the published image, configuration and commands, and Operations the production checklist.

Quick start: the next free slot

npm install slotlock postgres

Node.js 22.12+, PostgreSQL 16 or newer with btree_gist (created for you if missing), and postgres ^3.4.5 as a peer dependency. TypeScript declarations are included. The availability maths needs no database:

import { expandRules, findNextAvailable } from 'slotlock';

const searchWindow = {
  start: new Date('2026-09-14T00:00:00Z'),
  end: new Date('2026-09-21T00:00:00Z'),
};

const windows = expandRules(
  [{ rrule: 'FREQ=WEEKLY;BYDAY=MO,TU,WE,TH,FR', startMinutes: 9 * 60, durationMinutes: 8 * 60 }],
  searchWindow,
  'Europe/London',
);

export const slot = findNextAvailable({
  windows,
  busy: [{ start: new Date('2026-09-14T09:00:00Z'), end: new Date('2026-09-14T10:00:00Z') }],
  durationMs: 2 * 60 * 60 * 1000,
});
// slot: 2026-09-14 10:00–12:00 UTC, the first two free hours after the busy one

The TypeScript library guide sets up PostgreSQL, then books, holds and reads time under row-level security.

Connect an agent

Point any Streamable HTTP MCP client at http://localhost:8080/mcp with the token (on Slotlock Cloud, https://slotlock-api.pylota.io/mcp with an API key). Claude Code:

claude mcp add --transport http slotlock http://localhost:8080/mcp \
  --header "Authorization: Bearer $SLOTLOCK_AUTH_TOKEN"

On Slotlock Cloud, Claude Code can also install Slotlock as a plugin: its tools, and skills for booking without double-booking and for setting Slotlock up in a project. Put your API key in SLOTLOCK_API_KEY, then:

/plugin marketplace add PILOTAAI/slotlock
/plugin install slotlock@slotlock

Cursor, VS Code, the Claude API and the MCP and A2A SDKs are in Connect an agent, and every slotlock_* tool's input, output and errors in the Tools reference.

Documentation

For

Read

Running it

Quickstart, Self-hosting, Slotlock Cloud

API keys and scopes

API keys

Bookable hours and booking rules

Hours and booking rules

The dashboard, organizations and the assistant

Dashboard, on Cloudflare Workers

Agents: tools, errors and protocols

Connect an agent, Tools reference, Protocol reference

REST, the application API, changes and webhooks

REST API, Protocol reference

The library: store, holds, waitlists

TypeScript library

Recurring events

Recurring events

External calendars and iCalendar

External calendars

Rate limits and tenant limits

Limits

Maintenance, retention and the production checklist

Operations

Scaling and benchmarks

Scaling, Benchmarks

Clients for Python, Go, Rust, Java and .NET

Clients

Concepts and the security model

Concepts, Security, SECURITY.md

The exact rules

SPEC.md

Supported versions

Version

MCP

2026-07-28 (stateless), 2025-11-25, 2025-06-18

A2A

1.0, JSON-RPC binding

MCP Apps

io.modelcontextprotocol/ui 2026-01-26

Node.js

≥ 22.12 (CI: 22 and 24; the image runs 24)

PostgreSQL

16, 17 and 18 (CI runs the database suites on each; Compose ships 18)

postgres (peer)

^3.4.5

0.2.0 and older can double-book around daylight-saving changes: known issues.

Project status and boundaries

Slotlock is availability maths, holds and reservations, events with recurrence, coverage-aware free/busy, tenant isolation, iCalendar interchange, MCP and A2A with human confirmation and live updates, an MCP Apps view, REST with the application API, scoped API keys, a GitHub sign-in dashboard, maintenance, and clients for five languages. Hosted Slotlock runs it for you, or you self-host it. Provider sync (Google, Microsoft, CalDAV), notifications to people, and a human calendar app are yours to build around it. What each version promises is in VERSIONING.md.

Events need a finite duration (all-day events are whole local days; one event may last 3,660 days). Open-ended entries are refused rather than guessed.

The normative rules are in SPEC.md; tools can read slotlock.manifest.json without running package code. Report vulnerabilities as described in SECURITY.md. See CONTRIBUTING.md and GOVERNANCE.md for how the project runs.

License

Apache-2.0. Copyright 2026 TREFT LTD. Dependency notices are in NOTICE.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Scheduling and booking engine for AI agents. Check availability, hold slots, and confirm appointments with two-phase booking and conflict-free resource management.
      2
      Apache 2.0
    • F
      license
      Not graded
      quality
      B
      maintenance
      Enables customers and AI agents to check restaurant table availability and create bookings, returning confirmations or nearby alternative times when a slot is full, with atomic capacity control and idempotent handling.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables AI agents to discover bookable time slots, book and cancel meetings, list events, and enable or disable scheduling links. Also supports managing webhooks and exposes write/destructive operations with MCP annotations so clients can confirm before acting.
      12
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI assistants to discover availability, place expiring holds, and confirm or cancel appointments for connected booking businesses, with idempotent retries and explicit user consent.
      1
      Apache 2.0