gcal-mcp

MCP server for Google Calendar. Provides four tools: list calendars, list/search events, create events, and modify events.

Prerequisites

• uv
• A Google Cloud project with the Calendar API enabled

Google Cloud Setup

1. Go to Google Cloud Console
2. Create a project (or select an existing one)
3. Enable the Google Calendar API
4. Go to APIs & Services > Credentials
5. Create an OAuth 2.0 Client ID of type Desktop App
6. Download the credentials JSON and save it to ~/.config/gcal-mcp/credentials.json
7. Go to OAuth consent screen and add your Google account as a test user

Install & Authenticate

make install    # install dependencies
make auth       # opens browser for OAuth consent, prints calendars on success

Register with Claude Code

make register   # adds gcal-mcp as a user-scoped MCP server
make unregister # removes it

Tools

Tool	Description
list_calendars	List all accessible calendars
list_events	List or search events (supports time range, free-text query)
create_event	Create an event (supports attendees, location, description)
modify_event	Patch an existing event (only provided fields are updated)

Date/time values accept YYYY-MM-DD for all-day events or ISO datetime (YYYY-MM-DDTHH:MM) for timed events.

File Locations

• Credentials: ~/.config/gcal-mcp/credentials.json
• OAuth token: ~/.config/gcal-mcp/token.json