Google Calendar MCP Server

Example Usage

1. Add events from screenshots and images:Supported image formats: PNG, JPEG, GIF Images can contain event details like date, time, location, and description

2. Calendar analysis:

3. Check attendance:

4. Auto coordinate events:

5. Provide your own availability:

Requirements

1. Node.js (Latest LTS recommended)

2. TypeScript 5.3 or higher

3. A Google Cloud project with the Calendar API enabled

4. OAuth 2.0 credentials (Client ID and Client Secret)

Google Cloud Setup

1. Go to the Google Cloud Console

2. Create a new project or select an existing one.

3. Enable the Google Calendar API for your project. Ensure that the right project is selected from the top bar before enabling the API.

4. Create OAuth 2.0 credentials:

Installation

1. Clone the repository

2. Install dependencies (this also builds the js via postinstall):

3. 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 code (compiles src to build)

• npm run typecheck - Run TypeScript type checking without compiling

• npm run start - Start the compiled MCP server (using node build/index.js)

• npm run auth - Manually run the Google OAuth authentication flow.

• npm test - Run the unit/integration test suite using Vitest

• npm run test:watch - Run tests in watch mode

• npm run coverage - Run tests and generate a coverage report

Authentication

Automatic Authentication Flow (During Server Start)

1. Ensure gcp-oauth.keys.json is correctly named and placed in the project root.

2. Start the MCP server: npm start.

3. The server will check for existing, valid authentication tokens in .gcp-saved-tokens.json.

4. If valid tokens are found, the server starts normally.

5. If no valid tokens are found:

Manual Authentication Flow

1. Run the command: npm run auth

2. This script performs the same browser-based authentication flow described above.

3. Your browser will open, you authorize, and you'll see the success page indicating where tokens were saved.

4. The script will exit automatically upon successful authentication.

Token Management

• Authentication tokens are stored in .gcp-saved-tokens.json in the project root.

• This file is created automatically and should not be committed to version control (it's included in .gitignore).

• The server attempts to automatically refresh expired access tokens using the stored refresh token.

• If the refresh token itself expires (e.g., after 7 days if the Google Cloud app is in testing mode) or is revoked, you will need to re-authenticate using either the automatic flow (by restarting the server) or the manual npm run auth command.

Testing

• Run tests: npm test

• Run tests in watch mode: npm run test:watch

• Generate coverage report: npm run coverage

Security Notes

• The server runs locally and requires OAuth authentication.

• OAuth credentials (gcp-oauth.keys.json) and saved tokens (.gcp-saved-tokens.json) should never be committed to version control. Ensure they are added to your .gitignore file.

• For production use, consider getting your OAuth application verified by Google.

Usage with Claude Desktop

1. Add this configuration to your Claude Desktop config file. E.g. /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json:Note: Replace <absolute-path-to-project-folder> with the actual path to your project directory.

2. Restart Claude Desktop

Development

Troubleshooting

1. Authentication Errors / Connection Reset on Callback:

2. Tokens Expire Weekly:

3. Build Errors:

License

Google Calendar MCP Server

Example Usage

1. Add events from screenshots and images:Supported image formats: PNG, JPEG, GIF Images can contain event details like date, time, location, and description

2. Calendar analysis:

3. Check attendance:

4. Auto coordinate events:

5. Provide your own availability:

Requirements

1. Node.js (Latest LTS recommended)

2. TypeScript 5.3 or higher

3. A Google Cloud project with the Calendar API enabled

4. OAuth 2.0 credentials (Client ID and Client Secret)

Google Cloud Setup

1. Go to the Google Cloud Console

2. Create a new project or select an existing one.

3. Enable the Google Calendar API for your project. Ensure that the right project is selected from the top bar before enabling the API.

4. Create OAuth 2.0 credentials:

Installation

1. Clone the repository

2. Install dependencies (this also builds the js via postinstall):

3. 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 code (compiles src to build)

• npm run typecheck - Run TypeScript type checking without compiling

• npm run start - Start the compiled MCP server (using node build/index.js)

• npm run auth - Manually run the Google OAuth authentication flow.

• npm test - Run the unit/integration test suite using Vitest

• npm run test:watch - Run tests in watch mode

• npm run coverage - Run tests and generate a coverage report

Authentication

Automatic Authentication Flow (During Server Start)

1. Ensure gcp-oauth.keys.json is correctly named and placed in the project root.

2. Start the MCP server: npm start.

3. The server will check for existing, valid authentication tokens in .gcp-saved-tokens.json.

4. If valid tokens are found, the server starts normally.

5. If no valid tokens are found:

Manual Authentication Flow

1. Run the command: npm run auth

2. This script performs the same browser-based authentication flow described above.

3. Your browser will open, you authorize, and you'll see the success page indicating where tokens were saved.

4. The script will exit automatically upon successful authentication.

Token Management

• Authentication tokens are stored in .gcp-saved-tokens.json in the project root.

• This file is created automatically and should not be committed to version control (it's included in .gitignore).

• The server attempts to automatically refresh expired access tokens using the stored refresh token.

• If the refresh token itself expires (e.g., after 7 days if the Google Cloud app is in testing mode) or is revoked, you will need to re-authenticate using either the automatic flow (by restarting the server) or the manual npm run auth command.

Testing

• Run tests: npm test

• Run tests in watch mode: npm run test:watch

• Generate coverage report: npm run coverage

Security Notes

• The server runs locally and requires OAuth authentication.

• OAuth credentials (gcp-oauth.keys.json) and saved tokens (.gcp-saved-tokens.json) should never be committed to version control. Ensure they are added to your .gitignore file.

• For production use, consider getting your OAuth application verified by Google.

Usage with Claude Desktop

1. Add this configuration to your Claude Desktop config file. E.g. /Users/<user>/Library/Application Support/Claude/claude_desktop_config.json:Note: Replace <absolute-path-to-project-folder> with the actual path to your project directory.

2. Restart Claude Desktop

Development

Troubleshooting

1. Authentication Errors / Connection Reset on Callback:

2. Tokens Expire Weekly:

3. Build Errors:

License