Google Calendar MCP Server
This is a Model Context Protocol (MCP) server that provides integration with Google Calendar. It allows LLMs to read, create, and manage calendar events through a standardized interface.
Features
- List available calendars
- List events from a calendar
- Create new calendar events
- Update existing events
- Delete events
- Process events from screenshots and images
Requirements
- Node.js 16 or higher
- TypeScript 5.3 or higher
- A Google Cloud project with the Calendar API enabled
- OAuth 2.0 credentials (Client ID and Client Secret)
Project Structure
Google Cloud Setup
- Go to the Google Cloud Console
- Create a new project or select an existing one.
- Enable the Google Calendar API for your project. Ensure that the right project is selected from the top bar before enabling the API.
- Create OAuth 2.0 credentials:
- Go to Credentials
- Click "Create Credentials" > "OAuth client ID"
- Choose "User data" for the type of data that the app will be accessing
- Add your app name and contact information
- Add the following scopes (optional):
https://www.googleapis.com/auth/calendar.events
- Select "Desktop app" as the application type
- Add your email address as a test user under the OAuth Consent screen
- Note: it will take a few minutes for the test user to be added. The OAuth consent will not allow you to proceed until the test user has propogated.
Installation
- Clone the repository
- Install dependencies:
- Build the TypeScript code:
- Download your Google OAuth credentials from the Google Cloud Console (under "Credentials") and rename the file to
gcp-oauth.keys.json
and place it in the root directory of the project.
Available Scripts
npm run build
- Build the TypeScript codenpm run build:watch
- Build TypeScript in watch mode for developmentnpm run dev
- Start the server in development mode using ts-nodenpm run auth
- Start the authentication server for Google OAuth flow
Authentication
The server supports both automatic and manual authentication flows:
Automatic Authentication (Recommended)
- Place your Google OAuth credentials in a file named
gcp-oauth.keys.json
in the root directory of the project. - Start the MCP server:
- If no valid authentication tokens are found, the server will automatically:
- Start an authentication server (on ports 3000-3004)
- Open a browser window for the OAuth flow
- Save the tokens securely once authenticated
- Shut down the auth server
- Continue normal MCP server operation
The server automatically manages token refresh and re-authentication when needed:
- Tokens are automatically refreshed before expiration
- If refresh fails, clear error messages guide you through re-authentication
- Token files are stored securely with restricted permissions
Manual Authentication
For advanced users or troubleshooting, you can manually run the authentication flow:
This will:
- Start the authentication server
- Open a browser window for the OAuth flow
- Save the tokens and exit
Security Notes
- OAuth credentials are stored in
gcp-oauth.keys.json
- Authentication tokens are stored in
.gcp-saved-tokens.json
with 600 permissions - Tokens are automatically refreshed in the background
- Token integrity is validated before each API call
- The auth server automatically shuts down after successful authentication
- Never commit OAuth credentials or token files to version control
Usage
The server exposes the following tools:
list-calendars
: List all available calendarslist-events
: List events from a calendarcreate-event
: Create a new calendar eventupdate-event
: Update an existing calendar eventdelete-event
: Delete a calendar event
Using with Claude Desktop
- Add this configuration to your Claude Desktop config file. E.g.
/Users/<user>/Library/Application Support/Claude/claude_desktop_config.json
: - Restart Claude Desktop
Example Usage
Along with the normal capabilities you would expect for a calendar integration you can also do really dynamic things like add events from screenshots and images and much more.
- Add events from screenshots and images:Supported image formats: PNG, JPEG, GIF Images can contain event details like date, time, location, and description
- Check attendance:
- Auto coordinate events:
- Provide your own availability:
Development
Troubleshooting
Common issues and solutions:
- OAuth Token expires after one week (7 days)
- Apps that are in testing mode, rather than production, will need to go through the OAuth flow again after a week.
- OAuth Token Errors
- Ensure your
gcp-oauth.keys.json
is correctly formatted - Try deleting
.gcp-saved-tokens.json
and re-authenticating
- Ensure your
- TypeScript Build Errors
- Make sure all dependencies are installed:
npm install
- Check your Node.js version matches prerequisites
- Clear the build directory:
rm -rf build/
- Make sure all dependencies are installed:
- Image Processing Issues
- Verify the image format is supported
- Ensure the image contains clear, readable text
Security Notes
- The server runs locally and requires OAuth authentication
- OAuth credentials should be stored in
gcp-oauth.keys.json
in the project root - Authentication tokens are stored in
.gcp-saved-tokens.json
with restricted file permissions - Tokens are automatically refreshed when expired
- Never commit your OAuth credentials or token files to version control
- For production use, get your OAuth application verified by Google
License
MIT
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
使 LLM 能够通过标准化界面读取、创建和管理 Google 日历事件,包括列出日历、管理事件以及处理来自屏幕截图和图像的日历信息等功能。
Related MCP Servers
- -securityAlicense-qualityLets LLMs read and manage Google Calendar events.Last updated -1,222584MIT License
- -securityAlicense-qualityEnables comprehensive calendar management with capabilities to create, list, update, and delete events through a Model Context Protocol server integrated with Google Calendar.Last updated -8923MIT License
- -securityAlicense-qualityEnables AI assistants to manage Google Calendar through natural language interactions with features like creating, updating, and deleting events, searching calendars, and supporting natural language date/time inputs.Last updated -101MIT License
- -securityFlicense-qualityEnables programmatic management of Google Calendar events through natural language interactions, supporting creation, reading, updating, and deletion of events with features for recurring events, attendees, and reminders.Last updated -2