google_calendar_mcp

A Model Context Protocol (MCP) server for Google Calendar, written in Ruby.

It exposes the following tools to MCP clients:

  • list_calendars — list calendars accessible by the authenticated user
  • list_events — list events from a calendar (supports time range, free-text search, max results)
  • get_event — fetch detailed information about a specific event

The server requires only read-only access to your calendars (AUTH_CALENDAR_READONLY).

Installation

gem install google_calendar_mcp

Or add it to a Gemfile:

gem "google_calendar_mcp"

Setup

1. Create OAuth credentials

  1. Open the Google Cloud Console and create (or select) a project.
  2. Enable the Google Calendar API.
  3. Create an OAuth 2.0 Client ID of type Desktop app.
  4. Download the JSON file and save it as credentials.json.

2. Authorize the server

Run the server once from a working directory containing credentials.json:

google-calendar-mcp-server

On first run it prints an authorization URL. Open it in your browser, grant access, paste the code back in, and the server stores a refresh token in token.yaml.

3. Configure your MCP client

Example for Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "google-calendar": {
      "command": "google-calendar-mcp-server",
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/absolute/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/absolute/path/to/token.yaml"
      }
    }
  }
}

Environment variables

Variable Purpose
GOOGLE_CREDENTIALS_PATH Path to the OAuth client JSON file. Default: credentials.json.
GOOGLE_TOKEN_PATH Path to the stored refresh token YAML. Default: token.yaml.
GOOGLE_CREDENTIALS_JSON Raw OAuth client JSON. Overrides the file path when set.
GOOGLE_TOKEN_YAML Raw token YAML. Overrides the file path when set.

The *_JSON / *_YAML variables are convenient when running in environments where writing files is awkward (e.g. inside another process's config).

Development

bundle install
bundle exec ruby -Ilib exe/google-calendar-mcp-server

To build the gem locally:

gem build google_calendar_mcp.gemspec

License

MIT