Google Calendar MCP Server

A Model Context Protocol (MCP) server that integrates with Google Calendar, built with TypeScript.

Features

Seamless Google Calendar integration with OAuth 2.0 authentication
Persistent token storage for automatic authentication
List and manage calendars with comprehensive event operations
Create, read, update, and delete calendar events
Fetch calendar events between specified dates
Server-Sent Events (SSE) transport option for real-time updates
Simple integration with Claude and other MCP-compatible AI assistants

Installation

npm install -g mcp-google-calendar

Or run directly with:

npx -y mcp-google-calendar

Prerequisites

Node.js (v16 or higher)
Google Cloud Platform account
Google Calendar API enabled
OAuth 2.0 credentials

Setup

1. Google Cloud Configuration

Go to Google Cloud Console
Create a new project or select an existing one
Enable the Google Calendar API:
- Navigate to "APIs & Services" > "Library"
- Search for "Google Calendar API"
- Click "Enable"
Configure OAuth consent screen:
- Go to "APIs & Services" > "OAuth consent screen"
- Choose "External" user type (or "Internal" for Google Workspace)
- Fill in required information:
  - App name: mcp-calendar
  - User support email: (your email)
  - Developer contact information: (your email)
- Add scopes:
  - Click "Add or Remove Scopes"
  - Find and select "https://www.googleapis.com/auth/calendar.events"
  - Add your email as a test user
- Complete the setup
Create OAuth credentials:
- Go to "Credentials"
- Click "Create Credentials" > "OAuth Client ID"
- Choose "Desktop app" as application type
- Name it (e.g., "MCP Calendar Desktop Client")
- Download the JSON file and save as credentials.json in your project directory

2. Environment Configuration

Create a .env file in your project root:

# Server configuration
PORT=3420

# Google Calendar API configuration
CREDENTIALS_PATH=./credentials.json

Usage

Starting the Server

Start with standard WebSockets:

npx -y mcp-google-calendar

Start with Server-Sent Events (SSE):

npx -y mcp-google-calendar --sse

With Claude Desktop

Add this to your claude_desktop_config.json:

{
   "mcpServers": {
      "mcp-google-calendar": {
         "command": "npx",
         "args": ["-y", "mcp-google-calendar"],
         "env": {
            "CREDENTIALS_PATH": "/path/to/your/credentials.json"
         }
      }
   }
}

Authentication Process

The first time you run the server:

A browser window will open automatically
Sign in with your Google account
Grant the requested calendar permissions
The authentication token is saved to token.json

On subsequent launches:

The server uses the saved token automatically
No browser interaction is required unless the token expires

Available Tools

Tool	Description
`list_calendars`	Get all available calendars
`list_calendar_events`	Retrieve events between specified dates
`create_calendar_event`	Add a new event to your calendar
`get_calendar_event`	Fetch details for a specific event
`edit_calendar_event`	Modify an existing calendar event
`delete_calendar_event`	Remove an event from your calendar

Development

Clone and set up the project:

git clone https://github.com/am2rican5/mcp-google-calendar.git
cd mcp-google-calendar
npm install

Build the project:

npm run build

Run in development mode:

npm start

Security Considerations

⚠️ Important Security Warning ⚠️

credentials.json and token.json contain sensitive authentication information
Never commit these files to version control or share them publicly
Each user should create their own OAuth credentials
If you suspect credential compromise, revoke them immediately in Google Cloud Console
The token grants access to your Google Calendar data

License

This project is licensed under the MIT License - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

Integrations