README.md
MCP server for Google Calendar. Provides four tools: list calendars, list/search events, create events, and modify events.
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)Configuration
claude_desktop_config.json
{"mcpServers":{"gcal-mcp":{"command":"gcal-mcp"}}}Try it
→List all my accessible calendars.
→List events in my calendar for the next week.
→Search for events containing 'meeting' last month.
→Create a new event tomorrow at 10 AM with attendees john@example.com.
→Modify event ID abc123 to add location 'Office'.