README.md
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
- Go to Google Cloud Console
- Create a project (or select an existing one)
- Enable the Google Calendar API
- Go to APIs & Services > Credentials
- Create an OAuth 2.0 Client ID of type Desktop App
- Download the credentials JSON and save it to
~/.config/gcal-mcp/credentials.json - 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
Tools 4
list_calendarsList all accessible calendarslist_eventsList or search events (supports time range, free-text query)create_eventCreate an event (supports attendees, location, description)modify_eventPatch an existing event (only provided fields are updated)Try it
→List all my calendars to see which ones are available.
→Search for events in my calendar related to 'Project Meeting' for next week.
→Create a new event for a team sync on Friday at 2 PM.
→Update the description of my dentist appointment event to include the address.