When2Meet MCP Server

A Model Context Protocol server for When2Meet, enabling AI agents to create polls, read availability results, and find optimal meeting times programmatically.

Features

• Create polls — specific dates or days-of-the-week, in one API call

• Read results — get structured per-15-min availability data

• Find best slots — contiguous windows where the same people are free, with required/excluded people, date filters and a result limit

• Vote on behalf — submit availability for a named participant programmatically

Related MCP server: Google Calendar MCP Server

Quick Start

Install

Requires Python 3.10 or newer (uses zoneinfo and X | None annotations). On Windows the tzdata package supplies the timezone database and is installed automatically.

git clone https://github.com/LOGIC-10/when2meet-mcp.git
cd when2meet-mcp
pip install -r requirements.txt   # httpx + mcp[cli]; works with MCP SDK 1.x and 2.x

Run as MCP server

python server.py

Configure in your MCP client (Claude Desktop, Cursor, etc.):

{
  "mcpServers": {
    "when2meet": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

CLI usage (without MCP client)

# Create a poll (specific dates)
python server.py create --name "Weekly sync" --dates 2026-09-10 2026-09-11 2026-09-12

# Create a days-of-the-week poll
python server.py create --name "Office hours" --dates Monday Wednesday Friday --type days_of_week

# Read results (times rendered in --tz, default UTC)
python server.py results --url "https://when2meet.com/?12345-ABCDE" --tz Asia/Shanghai

# Find best slots (optionally: --require NAME.. --exclude NAME.. --dates DATE.. --limit N)
python server.py best --url "https://when2meet.com/?12345-ABCDE" --min-people 2 --min-minutes 30 --require Alice --limit 3

# Vote on behalf of a person (times must be 15-min slots of the poll; any ISO form)
python server.py vote --url "https://when2meet.com/?12345-ABCDE" --name Alice \
    --times 2026-09-10T09:00+08:00 2026-09-10T09:15+08:00 --tz Asia/Shanghai

Tools

How It Works

This server is a thin Python wrapper around When2Meet's existing HTTP endpoints. No backend changes required — it speaks the same protocol a browser would.

AvailabilityGrids.php is deliberately not used for reading: its hexAvailability comments are emitted in participant-creation order and only for people who have saved availability, while its PeopleNames are alphabetised, so the two cannot be paired reliably once names and creation order differ.

Every request is retried twice on transport errors and 5xx responses (0.5 s, then 1.5 s back-off); 4xx and site-level errors are reported immediately.

Tests

Offline tests run against six recorded poll pages (two people; six people whose alphabetical order differs from creation order; a creation-order probe; a poll spanning the US DST change with 280 slots; two days-of-the-week polls) plus an httpx.MockTransport for the create/vote/retry paths. Expected values are what was submitted to the site, not what the parser read back:

pip install -r requirements-dev.txt
python -m pytest -q

The tool wrappers work with both MCP SDK 1.x and 2.x and surface validation/HTTP errors as tool errors.

License

MIT