Googlecalendar

A Model Context Protocol (MCP) server for managing Google Calendar events.

Features

• List, create, update, delete, and get calendar events
• OAuth 2.0 and Service Account authentication
• Docker support for easy deployment
• MCP client integration (Cursor, Claude Desktop)

Quick Start

# Install dependencies
npm install

# Authenticate with Google
npm run auth

# Build and run
npm run build
npm start

For Docker: See DOCKER.md

Project Structure

googlecalendar-mcp/
├── src/
│   ├── index.ts           # Main MCP server
│   └── auth-helper.ts     # OAuth authentication helper
├── dist/                  # Compiled JavaScript (generated)
├── .env                   # Environment variables (create from .env.example)
├── package.json           # Node.js dependencies
├── tsconfig.json          # TypeScript configuration
├── Dockerfile             # Docker build configuration
├── docker-compose.yml     # Docker Compose setup
├── docker-helper.sh       # Docker convenience script
├── README.md              # This file
└── DOCKER.md              # Docker-specific documentation

Prerequisites

• Node.js 18+
• Google Cloud Project with Calendar API enabled
• OAuth 2.0 credentials

Setup

1. Set Up Google Calendar API

1.1 Create or Select a Project

1. Go to Google Cloud Console
2. Click on the project dropdown at the top of the page
3. Either:
   • Create a new project: Click "New Project", enter a project name (e.g., "Google Calendar MCP"), and click "Create"
   • Select an existing project: Choose from the list of existing projects

1.2 Enable Google Calendar API

1. In the Google Cloud Console, navigate to "APIs & Services" > "Library" (or use the search bar)
2. Search for "Google Calendar API"
3. Click on "Google Calendar API" from the search results
4. Click the "Enable" button
5. Wait for the API to be enabled (this usually takes a few seconds)
6. You should see a confirmation message: "API enabled"

Alternative Method:

• You can also enable it directly via this link (replace YOUR_PROJECT_ID with your actual project ID):

  https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=YOUR_PROJECT_ID
  

Troubleshooting:

• If you see an error like "Google Calendar API has not been used in project X before or it is disabled", make sure you've completed the steps above
• After enabling, wait a few minutes for the changes to propagate across Google's systems
• Verify the API is enabled by checking "APIs & Services" > "Enabled APIs" - you should see "Google Calendar API" listed

1.3 Create OAuth 2.0 Credentials

1. Navigate to "APIs & Services" > "Credentials" in the Google Cloud Console
2. If this is your first time, you may need to configure the OAuth consent screen:
   • Click "Configure Consent Screen"
   • Choose "External" (unless you have Google Workspace, then choose "Internal")
   • Fill in the required information:
     • App name: "Google Calendar MCP" (or any name you prefer)
     • User support email: Your email address
     • Developer contact information: Your email address
   • Click "Save and Continue" through the steps (you can skip optional steps for now)
3. Go back to "Credentials" and click "Create Credentials" > "OAuth client ID"
4. If prompted, choose "Desktop app" as the application type
5. Enter a name for your OAuth client (e.g., "Google Calendar MCP Client")
6. Click "Create"
7. Important: Copy the Client ID and Client Secret immediately - you'll need these for your .env file
8. Click "OK" to close the dialog

Note: The Client ID and Client Secret are sensitive credentials. Keep them secure and never commit them to version control.

2. Configure Environment Variables

Create a .env file in the root directory:

# Google Calendar API Credentials
GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback

# OAuth2 Token (will be generated after first authentication)
GOOGLE_ACCESS_TOKEN=
GOOGLE_REFRESH_TOKEN=

# Optional: Service Account JSON file path (alternative to OAuth)
# GOOGLE_SERVICE_ACCOUNT_PATH=./service-account.json

# Calendar ID (default is 'primary' for the primary calendar)
CALENDAR_ID=primary

3. Install Dependencies & Authenticate

npm install

Then authenticate:

If using OAuth 2.0, you can use the included authentication helper:

npm run auth

This will:

1. Automatically start a local HTTP server to catch the OAuth redirect
2. Open your browser with the authorization URL (or show you the URL to copy)
3. After you authorize, automatically capture the authorization code
4. Exchange the code for tokens automatically
5. Update your .env file with the tokens

Note: Make sure http://localhost:3000/oauth2callback is added to your OAuth client's authorized redirect URIs in Google Cloud Console.

Alternative: Manual Authentication

You can also use the Google OAuth 2.0 Playground:

1. Visit Google OAuth 2.0 Playground
2. Select "Calendar API v3" scopes
3. Authorize and get your tokens
4. Add the tokens to your .env file

4. Build the Project

npm run build

Usage

Running the Server

npm start

Or for development with auto-reload:

npm run dev

The server runs on stdio and communicates via the MCP protocol.

Available Tools

list_events

List events from Google Calendar.

Parameters:

• timeMin (optional): Lower bound for event end time (ISO 8601 format)
• timeMax (optional): Upper bound for event start time (ISO 8601 format)
• maxResults (optional): Maximum number of events (default: 10)
• calendarId (optional): Calendar ID (default: "primary")

Example:

{
  "timeMin": "2024-01-01T00:00:00Z",
  "timeMax": "2024-12-31T23:59:59Z",
  "maxResults": 20
}

create_event

Create a new event in Google Calendar.

Parameters:

• summary (required): Title of the event
• startDateTime (required): Start date/time (ISO 8601 format)
• endDateTime (required): End date/time (ISO 8601 format)
• description (optional): Event description
• location (optional): Event location
• timeZone (optional): Time zone (default: "UTC")
• attendees (optional): Array of attendee email addresses
• calendarId (optional): Calendar ID (default: "primary")

Example:

{
  "summary": "Team Meeting",
  "description": "Weekly team sync",
  "startDateTime": "2024-01-15T10:00:00Z",
  "endDateTime": "2024-01-15T11:00:00Z",
  "timeZone": "America/New_York",
  "location": "Conference Room A",
  "attendees": ["[email protected]"]
}

update_event

Update an existing event.

Parameters:

• eventId (required): ID of the event to update
• All other parameters are optional (same as create_event)

delete_event

Delete an event from the calendar.

Parameters:

• eventId (required): ID of the event to delete
• calendarId (optional): Calendar ID (default: "primary")

get_event

Get details of a specific event.

Parameters:

• eventId (required): ID of the event to retrieve
• calendarId (optional): Calendar ID (default: "primary")

MCP Client Configuration

Add to your MCP client config (Cursor, Claude Desktop):

{
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["/absolute/path/to/dist/index.js"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id",
        "GOOGLE_CLIENT_SECRET": "your_client_secret",
        "GOOGLE_ACCESS_TOKEN": "your_access_token",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token"
      }
    }
  }
}

For Docker setup, see DOCKER.md

Troubleshooting

"Google Calendar API has not been used in project X before or it is disabled"

This error means the Google Calendar API is not enabled in your Google Cloud project.

Solution:

1. Go to Google Cloud Console
2. Select your project
3. Navigate to "APIs & Services" > "Library"
4. Search for "Google Calendar API" and enable it
5. Wait a few minutes for the changes to propagate
6. Retry your request

Direct link to enable API: Replace YOUR_PROJECT_ID with your actual project ID:

https://console.cloud.google.com/apis/library/calendar-json.googleapis.com?project=YOUR_PROJECT_ID

"Missing Google OAuth credentials" error

• Check that .env file exists and has correct values
• Verify GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set
• Make sure there are no extra spaces or quotes around the values
• Ensure the .env file is in the project root directory

"Invalid credentials" error

• Verify your Client ID and Client Secret are correct
• Check that Google Calendar API is enabled in your project
• Ensure OAuth consent screen is configured
• Make sure you're using the correct project credentials

"Token expired" error

• Re-run npm run auth to get new tokens
• Or use Google OAuth 2.0 Playground to refresh tokens
• Update your .env file with the new tokens

Server won't start

• Check Node.js version: node --version (needs 18+)
• Rebuild the project: npm run build
• Check for errors: npm start
• Verify all dependencies are installed: npm install

MCP Server Connection Issues

• Verify the path in mcp.json is correct and uses absolute paths
• Check that dist/index.js exists (run npm run build if missing)
• Ensure environment variables are properly set in your MCP configuration
• Restart your MCP client (Cursor/Claude Desktop) after configuration changes

Alternative: Service Account

For server-to-server authentication:

1. Create a service account in Google Cloud Console
2. Download the JSON key file
3. Share your calendar with the service account email
4. Set GOOGLE_SERVICE_ACCOUNT_PATH in .env

Development

npm run dev  # Development mode with auto-reload

License

MIT