Integrations
Enables reading, creating, and managing Google Calendar events, including listing available calendars, creating/updating/deleting events, and processing events from screenshots and images.
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:Copy
- Build the TypeScript code:Copy
- 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:Copy
- 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
:Copy - 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 descriptionCopy
- Check attendance:Copy
- Auto coordinate events:Copy
- Provide your own availability:Copy
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.
Enables LLMs to read, create, and manage Google Calendar events through a standardized interface, including features like listing calendars, managing events, and processing calendar information from screenshots and images.
Related MCP Servers
- -securityAlicense-qualityLets LLMs read and manage Google Calendar events.Last updated -44213TypeScriptMIT License
- AsecurityAlicenseAqualityProvides tools for interacting with Gmail and Calendar APIs. This server enables you to manage your emails and calendar events programmatically through the MCP interface.Last updated -813JavaScriptMIT 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 -131TypeScriptMIT License
- -securityAlicense-qualityEnables interaction with Gmail and Google Calendar using the MCP protocol, supporting multiple Google accounts, email management, and calendar operations through natural language.Last updated -5TypeScriptMIT License