Set Up an MCP Calendar Server

Command references used in this guide: nylas mcp install for registering the server, nylas mcp serve for starting the STDIO proxy, nylas mcp status for confirming configuration, and nylas calendar availability for the free/busy logic the server exposes.

How do I install the Nylas MCP calendar server?

An MCP calendar server is a local process that exposes calendar operations — list events, create events, check free/busy — as tools an AI client calls over the Model Context Protocol. The Nylas CLI ships one built in. Installing it takes three steps and runs in under 60 seconds if Homebrew is already present.

The calendar tools ride on the same server entry as the email tools, so no separate calendar install exists. MCP reached 97 million monthly SDK downloads by March 2026, and the public registry listed over 9,400 servers. For a side-by-side with the mailbox setup, see the MCP email server guide.

The commands below add the CLI and authenticate the account. The OAuth flow opens a browser, stores the grant in ~/.config/nylas/, and refreshes tokens automatically every 3,600 seconds. For shell-script, PowerShell, and Go install methods, see the getting started guide.

# Install the CLI (macOS / Linux)
brew install nylas/nylas-cli/nylas

# Authenticate your calendar account
nylas auth login

# Confirm the grant is active
nylas auth whoami

Once authenticated, register the server with nylas mcp install. The command detects which of the 5 supported assistants are installed, writes the correct JSON config, and for Claude Code adds the tool-permission entries so prompts are pre-approved. Run it once per machine.

# Register the server (interactive -- detects installed tools)
nylas mcp install

# Or target a specific assistant
nylas mcp install --assistant claude-code
nylas mcp install --assistant cursor
nylas mcp install --assistant windsurf
nylas mcp install --assistant vscode
nylas mcp install --assistant claude-desktop

# Or install for all detected assistants at once
nylas mcp install --all

How do I configure the calendar MCP server per tool?

The nylas mcp install command writes the config for you, but knowing what it writes helps with debugging. Every one of the 5 supported assistants uses the same JSON block: it points at the nylas binary and passes mcp serve as the startup argument. The server speaks JSON-RPC over STDIO, which all of them expect.

// The config block is identical for every tool -- only the file path differs
{
  "mcpServers": {
    "nylas": {
      "command": "nylas",
      "args": ["mcp", "serve"]
    }
  }
}

Place that block in the config file for your assistant. The mcp serve proxy injects the grant ID automatically and converts every timestamp to your system timezone, so the agent never needs to ask which account or which offset to use. The table below lists where each tool reads its config.

What calendar tools does the MCP server expose?

The Nylas calendar MCP server exposes 5 calendar tools plus 4 time-conversion utilities. The calendar tools cover the read and write surface an assistant needs: list calendars, query events, create and update events, and check availability across participants. Each maps to the same logic as the nylas calendar command family.

The availability tool is the one assistants reach for first, because scheduling starts with finding open time. You can run the same check from the terminal to confirm the data the agent will see. The command below returns busy slots for two people over the next day in under 1 second.

# Free/busy across two participants -- the data the availability tool returns
nylas calendar availability check \
  --emails alice@example.com,bob@example.com \
  --start "tomorrow 9am" --end "tomorrow 5pm"

# Find concrete 30-minute slots when everyone is free
nylas calendar availability find \
  --participants alice@example.com,bob@example.com \
  --duration 30 --interval 15

When the assistant decides on a slot, it calls create_event, which maps to the create command below. The CLI defaults --busy to true and sets the end time to 1 hour after the start when you omit --end. Passing --participant more than once invites multiple attendees on the underlying calendar API.

# Create the event the agent proposed
nylas calendar events create \
  --title "Sprint planning" \
  --start "2026-06-12 10:00" --end "2026-06-12 11:00" \
  --participant "alice@example.com" \
  --participant "bob@example.com" \
  --location "Zoom"

How do I verify the calendar MCP server works?

The nylas mcp status command checks all 5 supported assistants in one pass and reports which have the Nylas server configured. It reads each config file, confirms the nylas entry exists, and flags installed tools that are not yet connected. Run it right after install to catch a missing entry.

nylas mcp status

For an end-to-end test, open your assistant and ask a question that exercises the calendar tools, such as a request to find a free hour next Tuesday. That routes through the availability tool and confirms the full chain: STDIO transport, grant injection, the API call, and timezone conversion. If the assistant returns real open slots, reads work.

Here is the TL;DR catch: read tools work as soon as the server is configured, but create_event writes to a real calendar and sends invites. The grant's OAuth scope decides whether writes succeed — a read-only calendar scope returns a 403 on event creation while free/busy and event listing still work. Confirm the grant carries calendar write scope before expecting the agent to book meetings.

Common errors and fixes

Roughly 90% of reported calendar MCP issues trace to 3 causes: the CLI is not authenticated, the grant lacks write scope, or the assistant cached an old config. Each fix takes under 60 seconds.

Why use MCP instead of calling the calendar API directly?

MCP and direct calendar API calls solve different problems. MCP gives an AI client a standard way to discover and call availability and event tools with zero glue code, while direct API calls are faster and cheaper per operation for bulk work. The best agents use both: MCP for interactive scheduling, direct API for batch sync. The protocol removes provider-specific quirks the agent would otherwise handle itself.

Calendar APIs diverge in ways MCP hides. Google's events.insert endpoint and Microsoft Graph's POST to /me/events use different field names, recurrence formats, and free/busy semantics. The iCalendar RFC 5545 standardizes the event model, but each provider implements it differently. The MCP server normalizes all of this, so the agent calls one create_event tool regardless of backend, the same way the email server unifies sending across providers.

Next steps

• Set Up an MCP Contacts Server — Expose contact search and read tools to an AI client over MCP with…
• Give an AI Agent Calendar Access — Wrap nylas calendar availability and events as agent tools
• Full command reference — every flag, subcommand, and example
• Set up an MCP email server — the mailbox counterpart that shares the same server entry
• Connect Claude to your email — the Claude-specific MCP walkthrough
• Email MCP server for AI agents — tools, architecture, and example prompts
• Manage your calendar from the terminal — the full availability and event command reference
• Export contacts to CSV — pull attendee lists for scheduling
• Getting started with Nylas CLI — install methods and first-run setup
• Model Context Protocol specification — the protocol standard maintained by the Linux Foundation
• Nylas MCP documentation — the upstream server reference