google-calendar

Dependency-free local emulator for Google Calendar API v3 JSON REST calls. It is designed for googleapis Calendar clients, raw fetch, and AI-agent test flows that need calendars, events, ACL rules, free/busy, colors, settings, and watch channels without calling https://www.googleapis.com/calendar/v3.

Default port: 4615

Quick start

import { google } from "googleapis";
import { GoogleCalendarServer } from "./services/google-calendar/src/server.js";

const server = new GoogleCalendarServer(4615);
await server.start();

const calendar = google.calendar({ version: "v3", auth: "not-used-by-parlel" });
calendar.context._options.rootUrl = "http://127.0.0.1:4615/";

const created = await calendar.calendars.insert({
  requestBody: { summary: "Engineering", timeZone: "UTC" },
});

await calendar.events.insert({
  calendarId: created.data.id,
  requestBody: {
    summary: "Planning",
    start: { dateTime: "2026-01-01T10:00:00.000Z" },
    end: { dateTime: "2026-01-01T11:00:00.000Z" },
  },
});

await server.stop();

Reset state with server.reset() or POST /_parlel/reset. Health is available at GET /_parlel/health.

Implemented operations

Calendars

Calendar list

ACL

Events

Other resources

All endpoints also accept the short /v3/... prefix.

Access via MCP / preview URL

When run inside a parlel sandbox, point Google Calendar API clients at the preview URL or local base URL, for example http://127.0.0.1:4615/. Node googleapis users can set calendar.context._options.rootUrl; raw clients can call the documented /calendar/v3/... paths directly. MCP-driven agents can reset state between scenarios with POST /_parlel/reset.

Surface coverage

Legend: ✅ supported · ◐ accepted-not-enforced · ✓ by design · ⟳ roadmap.

Error codes & shapes

Errors use the Google Calendar API error envelope documented in the Calendar error guide. The body does not include a top-level error.status member.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "notFound",
        "message": "Not Found"
      }
    ],
    "code": 404,
    "message": "Not Found"
  }
}

Common codes:

Because auth is accepted-not-enforced, the emulator does not emit real Google 401 authError responses for missing or invalid OAuth credentials.

Manifest

See services/google-calendar/manifest.json:

• name: google-calendar, image: parlel/google-calendar:0.1
• port: 4615, protocol: http, healthcheck: /_parlel/health, startup approximately 100ms
• env: GOOGLE_CALENDAR_EMULATOR_HOST, GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT

Configuration — test.env

Copy these into your test.env (used by the bridge sidecar flow). Tokens are Parlel's seeded test credentials — any non-empty value is accepted by the emulator, so you rarely need to change them. Swap in real credentials only when pointing at the live service in prod.env.

GOOGLE_CALENDAR_EMULATOR_HOST=http://parlel-bridge:4615
GOOGLE_CLOUD_PROJECT=parlel
GCLOUD_PROJECT=parlel