calendar-mcp

An MCP (Model Context Protocol) server that reads your Microsoft 365 calendar and answers two questions for any day:

• What meetings do I have? (get_todays_meetings)
• When am I free? (get_availability — busy blocks + free gaps within working hours)

It authenticates as you using the Microsoft device code flow (no admin consent, no app secrets) and reads your calendar via the Microsoft Graph API.

This README doubles as a learning guide structured around four topics:

1. Understand MCP Fundamentals & Architecture
2. Practical MCP Server Implementation & Deployment
3. Integrate MCP with a Real Workflow
4. Reinforcement & Validation

---

1. Understand MCP Fundamentals & Architecture

What MCP is. The Model Context Protocol is an open standard that lets an AI client (Claude Desktop, Claude Code, etc.) call external tools, read resources, and use prompts through a uniform JSON-RPC interface. Instead of every integration being bespoke, an MCP server exposes capabilities and any MCP client can use them.

The three roles.

| Role | In this project | |------|-----------------| | Host / Client | Claude Desktop or Claude Code — starts the server, sends requests | | Server | calendar-mcp — exposes the two calendar tools | | Transport | stdio — JSON-RPC messages over stdin/stdout |

Message flow (this server):

Client                         calendar-mcp (server)              Microsoft Graph
  │  initialize ──────────────────▶                                      │
  │  ◀────────────── capabilities  │                                      │
  │  tools/list ──────────────────▶                                      │
  │  ◀──────── [get_todays_meetings, get_availability]                    │
  │  tools/call get_availability ─▶                                      │
  │                                │  acquireTokenSilent (MSAL cache)     │
  │                                │  GET /me/calendarView ──────────────▶│
  │                                │  ◀──────────────── events            │
  │  ◀──── text: free/busy slots   │                                      │

Architecture of this codebase (one responsibility per file — see team standards):

src/
├── index.ts                      MCP server: registers tools, formats output
├── login.ts                      one-time device-code sign-in CLI
├── config.ts                     env validation (Zod) → Config
├── logger.ts                     structured logger → STDERR (stdout is the protocol!)
├── time.ts                       timezone math (wall-clock ⇄ UTC instants)
├── types/calendar.ts             Zod schemas + domain types + Result<T>
└── services/
    ├── auth-service.ts           MSAL device-code flow + token cache persistence
    ├── graph-service.ts          calls Microsoft Graph, normalizes events
    └── availability-service.ts   merges busy blocks, computes free gaps (pure)

Two architectural rules worth internalizing:

1. stdout is sacred. A stdio MCP server speaks JSON-RPC on stdout. Any stray

console.log corrupts the stream. That's why logger.ts writes only to stderr.

1. Auth is separated from serving. The interactive sign-in lives in a

separate login script. The server itself only refreshes tokens silently, so it never needs to prompt a human mid-request.

---

2. Practical MCP Server Implementation & Deployment

Prerequisites

• Node.js ≥ 18 (you have v22 ✓)
• A Microsoft 365 / Outlook account with a calendar
• An Azure App Registration (free — guide below)

Step A — Create an Azure App Registration

You need a Client ID and Tenant ID. This app uses delegated permissions (it acts as you), so no client secret and no admin consent are required.

1. Go to <https://portal.azure.com> → search App registrations → New registration.
2. Name: calendar-mcp (anything).
3. Supported account types:

• Just your work/school account → Accounts in this organizational directory only.
• Personal Microsoft accounts too → Accounts in any org directory and personal Microsoft accounts.

1. Redirect URI: leave blank. Click Register.
2. On the Overview page, copy:

• Application (client) ID → this is AZURE_CLIENT_ID
• Directory (tenant) ID → this is AZURE_TENANT_ID

(or use common if you chose a multi-tenant/personal account type).

1. Left menu → Authentication → Advanced settings → set

Allow public client flows to Yes. (Required for device code flow.) Save.

1. Left menu → API permissions → Add a permission → Microsoft Graph

→ Delegated permissions → search and add Calendars.Read → Add permissions.

• Personal accounts consent on first sign-in; org accounts may need an admin to

Grant admin consent depending on tenant policy.

Step B — Configure the project

cp .env.example .env
# edit .env and set AZURE_CLIENT_ID (and AZURE_TENANT_ID if not "common")

| Variable | Required | Default | Notes | |----------|----------|---------|-------| | AZURE_CLIENT_ID | ✅ | — | Application (client) ID GUID | | AZURE_TENANT_ID | | common | Tenant GUID, or common for personal/multi-tenant | | TOKEN_CACHE_PATH | | ~/.calendar-mcp/token-cache.json | Where tokens are stored (chmod 600) | | TIMEZONE | | system tz | IANA name, e.g. Asia/Kolkata | | WORKING_HOURS_START | | 9 | Hour 0–23 for availability window | | WORKING_HOURS_END | | 18 | Hour 1–24 for availability window |

Step C — Install, sign in, build

npm install
npm run login    # device-code flow: opens a URL, you paste a code, sign in ONCE
npm run build    # compile TypeScript → dist/

npm run login prints something like:

To sign in, use a web browser to open https://microsoft.com/devicelogin
and enter the code ABCD-EFGH to authenticate.

After success, a token cache is written to TOKEN_CACHE_PATH. The server uses it silently from then on.

Step D — Run it

npm start          # runs dist/index.js over stdio
# or during development:
npm run dev        # runs src/index.ts via tsx (no build step)

Deployment: wire it into an MCP client

Claude Desktop — edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "calendar": {
      "command": "node",
      "args": ["/Users/khushal/Documents/practice project/calendar-mcp/dist/index.js"],
      "env": {
        "AZURE_CLIENT_ID": "your-client-id-guid",
        "AZURE_TENANT_ID": "common",
        "TIMEZONE": "Asia/Kolkata"
      }
    }
  }
}

Claude Code (CLI):

claude mcp add calendar -- node "/Users/khushal/Documents/practice project/calendar-mcp/dist/index.js"

Restart the client. The calendar server's tools will appear.

Note: run npm run login first so the token cache exists before the client launches the server. The server never prompts for sign-in itself.

---

3. Integrate MCP with a Real Workflow

Once connected, you talk to your calendar in natural language and the model picks the right tool:

| You ask… | Tool called | Result | |----------|-------------|--------| | "What meetings do I have today?" | get_todays_meetings | Ordered list with times, locations, organizers | | "What's on my calendar on 2026-06-25?" | get_todays_meetings {date} | Same, for that date | | "When am I free today?" | get_availability | Free gaps + busy blocks within 9–18 | | "Do I have a 2-hour block this afternoon?" | get_availability | Model reads the free slots and reasons over them | | "Find me 30 min between meetings before 2pm" | get_availability {workingHoursEnd:14} | Narrowed window |

Why this composes well: get_availability returns structured free/busy spans, so the model can chain reasoning ("schedule the review in your longest free block") without you doing the arithmetic. This is the real value of MCP — the tool provides facts; the model provides judgment.

Example tool output:

Availability for 2026-06-23 (Asia/Kolkata), working hours 09:00–18:00:
Total free: 5h 30m

Free slots:
  • 9:00 AM – 11:00 AM
  • 11:30 AM – 1:00 PM
  • 2:00 PM – 4:00 PM

Busy blocks:
  • 11:00 AM – 11:30 AM
  • 1:00 PM – 2:00 PM
  • 4:00 PM – 6:00 PM

---

4. Reinforcement & Validation

Validate the protocol without a calendar

The server answers initialize and tools/list before any auth. Smoke-test with raw JSON-RPC (a well-formed dummy client ID is enough):

printf '%s\n%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
 | AZURE_CLIENT_ID=11111111-1111-1111-1111-111111111111 node dist/index.js 2>/dev/null

You should see the server info and both tool schemas.

Validate the auth boundary

Calling a tool with no cached login returns a friendly, non-crashing error:

printf '%s\n%s\n' \
 '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}' \
 '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"get_todays_meetings","arguments":{}}}' \
 | AZURE_CLIENT_ID=11111111-1111-1111-1111-111111111111 TOKEN_CACHE_PATH=/tmp/none.json node dist/index.js 2>/dev/null
# → "Not signed in. Run `npm run login` ..."

Validate against your real calendar

npm run login        # if you haven't already
npx @modelcontextprotocol/inspector node dist/index.js

The MCP Inspector opens a UI where you can call get_todays_meetings and get_availability and see live results from your calendar.

Checklist

• [ ] npm run build compiles with no errors
• [ ] tools/list returns both tools
• [ ] npm run login completes and writes the token cache
• [ ] get_todays_meetings matches what you see in Outlook
• [ ] get_availability free + busy spans add up to the working window
• [ ] All-day events do not block availability; tentative meetings show as busy
• [ ] Timezone is correct (compare a meeting time vs Outlook)

Things to try next (stretch goals)

• Add a find_slot tool that takes a duration and returns the earliest free block.
• Expose the calendar as an MCP resource (read-only data) in addition to tools.
• Support multiple calendars or a freeBusy query across attendees

(/me/calendar/getSchedule).

• Cache Graph responses briefly to cut latency on repeated calls.

---

Security notes

• The token cache (TOKEN_CACHE_PATH) holds refresh/access tokens. It's written

chmod 600 and is git-ignored. Treat it like a password.

• Only Calendars.Read is requested — the server cannot modify your calendar.
• No secrets are stored in code; the Client ID is not a secret but lives in env.

Project scripts

| Command | Does | |---------|------| | npm run dev | Run the server from source (tsx) | | npm run build | Compile to dist/ | | npm start | Run the compiled server | | npm run login | One-time device-code sign-in (source) | | npm run login:prod | Same, from compiled dist/ | | npm run typecheck | Type-check without emitting |