Examples

Calendar API to MCP

Calendar MCP tools are valuable because scheduling is structured but full of edge cases: time zones, attendees, conflicts, privacy, recurrence, and user consent. Good tools make those constraints explicit.

Updated Jun 25, 20267 min read

Implementation

Path to ship.

Generate availability and event read tools before enabling event creation.

Normalize time zones and require ISO timestamps for all scheduling calls.

Separate draft meeting creation from direct send if your workflow needs approval.

Test conflicts, missing attendees, daylight saving boundaries, and private event summaries.

Guide

Recommended tool surface

The safest first calendar tools find free time, list upcoming events, and inspect one event. They help the agent reason about time without changing anyone's schedule.

For writes, use create_draft_event or create_meeting_with_attendees rather than a generic event mutation tool. Include attendees, timezone, duration, and conflict policy as required fields.

calendar_find_free_windows

Finds free windows across one or more calendars for a date range and duration.

Generated input schema

{
  "type": "object",
  "properties": {
    "calendar_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 },
    "start": { "type": "string", "format": "date-time" },
    "end": { "type": "string", "format": "date-time" },
    "duration_minutes": { "type": "integer", "minimum": 15, "maximum": 240 },
    "timezone": { "type": "string" }
  },
  "required": ["calendar_ids", "start", "end", "duration_minutes", "timezone"]
}

Example tools/call

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "calendar_find_free_windows",
    "arguments": {
      "calendar_ids": ["primary", "team-sales"],
      "start": "2026-07-02T09:00:00-07:00",
      "end": "2026-07-02T17:00:00-07:00",
      "duration_minutes": 30,
      "timezone": "America/Los_Angeles"
    }
  }
}

calendar_create_meeting_draft

Creates a meeting draft with attendees and conference details without sending invites automatically.

Generated input schema

{
  "type": "object",
  "properties": {
    "calendar_id": { "type": "string" },
    "title": { "type": "string" },
    "start": { "type": "string", "format": "date-time" },
    "end": { "type": "string", "format": "date-time" },
    "attendees": { "type": "array", "items": { "type": "string" }, "maxItems": 25 },
    "description": { "type": "string", "maxLength": 2000 }
  },
  "required": ["calendar_id", "title", "start", "end", "attendees"]
}

Example tools/call

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "calendar_create_meeting_draft",
    "arguments": {
      "calendar_id": "primary",
      "title": "Security review",
      "start": "2026-07-02T13:00:00-07:00",
      "end": "2026-07-02T13:30:00-07:00",
      "attendees": ["alex@example.com", "sam@example.com"],
      "description": "Draft created by support agent. Human approval required before send."
    }
  }
}

Guide

Production guardrails

Private event details should be summarized cautiously. If an event is marked private, the tool should return busy status and time bounds without leaking title, notes, guests, or attachments.

Recurring event edits need separate review. A single bad recurrence update can damage an entire calendar series.

FAQ

Common questions.

Should calendar tools send invites automatically?

Only after the workflow is proven. Draft-first tools are safer for assistants that need human approval.

What calendar edge case matters most?

Time zone handling. Require ISO date-times and an explicit timezone in every scheduling tool.