Labsco
galacoder logo

Google Calendar

★ 1

from galacoder

An MCP server for Google Calendar, enabling LLMs to read, create, and manage calendar events.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#email#automation#calendar#cloud#maps#security

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

Project Structure

google-calendar-mcp/
├── src/           # TypeScript source files
├── build/         # Compiled JavaScript output
├── llm/           # LLM-specific configurations and prompts
├── package.json   # Project dependencies and scripts
└── tsconfig.json  # TypeScript configuration

Available Scripts

  • npm run build - Build the TypeScript code
  • npm run build:watch - Build TypeScript in watch mode for development
  • npm run dev - Start the server in development mode using ts-node
  • npm run auth - Start the authentication server for Google OAuth flow

Authentication

The server supports both automatic and manual authentication flows:

Automatic Authentication (Recommended)

  1. Place your Google OAuth credentials in a file named gcp-oauth.keys.json in the root directory of the project.
  2. Start the MCP server: 
    npm start
  3. 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:

npm run auth

This will:

  1. Start the authentication server
  2. Open a browser window for the OAuth flow
  3. 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

Using 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:

    {
  "mcpServers": {
    "google-calendar": {
      "command": "node",
      "args": ["path/to/build/index.js"]
    }
  }
}

  2. Restart Claude Desktop

Development

Troubleshooting

Common issues and solutions:

  1. 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.

  2. OAuth Token Errors

    • Ensure your gcp-oauth.keys.json is correctly formatted
    • Try deleting .gcp-saved-tokens.json and re-authenticating

  3. 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/

  4. 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