google-calendar-mcp
local-only server
The server can only run on the client’s local machine because it depends on local resources.
Integrations
Allows LLMs to read, create, and manage calendar events through a standardized interface, including listing calendars, listing events, creating events, updating events, 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
- Calendar Management:
- List and select available calendars
- View calendar events with detailed information
- Create new calendar events
- Update existing events
- Delete events
- Manage event attendees and responses
- Set and manage event reminders (email and popup notifications)
- Support for multiple calendars (both primary and secondary)
- Security & Authentication:
- Secure OAuth 2.0 authentication flow
- Automatic token refresh handling
- Secure storage of credentials and tokens
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
- Calendar analysis:Copy
- Check attendance:Copy
- Auto coordinate events:Copy
- Provide your own availability:Copy
Requirements
- Node.js (Latest LTS recommended)
- 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.
- Note about test mode: While an app is in test mode the auth tokens will expire after 1 week and need to be refreshed by running
npm run auth
.
Installation
- Clone the repository
- Install dependencies (this also builds the js, postinstall):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.- Alternatively, copy the provided template file:
cp gcp-oauth.keys.example.json gcp-oauth.keys.json
and populate it with your credentials from the Google Cloud Console.
- Alternatively, copy the provided template file:
Available Scripts
npm run build
- Build the TypeScript code and run type checksnpm run typecheck
- Run TypeScript type checkingnpm run start
- Start the compiled servernpm 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
(you can use the includedgcp-oauth.keys.example.json
template as a starting point) - 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 MCP tools:
- Calendar Management:
list-calendars
: List all available calendarsget-calendar
: Get details of a specific calendarlist-events
: List events from a calendar with filtering optionsget-event
: Get detailed information about a specific eventcreate-event
: Create a new calendar eventupdate-event
: Update an existing calendar eventdelete-event
: Delete a calendar eventlist-colors
: List available colors for events and calendars
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
:Note: ReplaceCopy<absolute-path-to-project>
with the actual path to your project directory. - Restart Claude Desktop
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 (check against the structure ingcp-oauth.keys.example.json
) - 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 - 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
Lets LLMs read and manage Google Calendar events.