gcal-mcp

A Model Context Protocol (MCP) server for read-only Google Calendar integration. Provides calendar access to AI assistants through the MCP standard.

Features

• get_events_today - Get all calendar events for today
• get_events_week - Get all calendar events for the current week (Monday to Sunday)
• get_pending_invites - Get calendar invitations requiring a response
• find_available_slot - Find available time slots for scheduling meetings

Prerequisites

• Node.js 18+
• A Google Cloud project with Calendar API enabled
• OAuth 2.0 credentials (Desktop app type)

Setup

1. Create Google Cloud OAuth Credentials

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Calendar API
4. Go to APIs & Services > Credentials
5. Click Create Credentials > OAuth client ID
6. Select Desktop app as the application type
7. Download the JSON file and save it as client_secret*.json in the project root

2. Install Dependencies

npm install

3. Authenticate

Run the auth script to authorize access to your calendar:

npm run auth

This will open a browser window for Google OAuth consent. After authorization, a token.json file will be created.

4. Build

npm run build

Usage

With Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "gcal": {
      "command": "node",
      "args": ["/path/to/gcal-mcp/dist/index.js"]
    }
  }
}

Standalone

npm start

Development

npm run dev

Tools Reference

get_events_today

Returns all events scheduled for the current day.

get_events_week

Returns all events for the current week (Monday through Sunday), grouped by day.

get_pending_invites

Returns calendar invitations where you haven't responded yet (needsAction status). Looks 30 days ahead.

find_available_slot

Finds available meeting slots based on your calendar.

Parameter	Type	Required	Description
duration_minutes	number	Yes	Meeting duration (15-480 minutes)
search_days	number	No	Days to search ahead (default: 7, max: 14)
working_hours_start	number	No	Start hour (default: 9)
working_hours_end	number	No	End hour (default: 17)

Security Notes

⚠️ Never commit sensitive files:

• client_secret*.json - Your OAuth client credentials
• token.json - Your access/refresh tokens

These are already in .gitignore.

License

ISC