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.

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