google-calendar-mcp-server

Kashyab19/google-calendar-mcp-server

3.2

If you are the rightful owner of google-calendar-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

A Model Context Protocol (MCP) server that integrates with Google Calendar using the Smithery framework, allowing AI assistants to manage calendar data and user authentication.

Tools
13
Resources
0
Prompts
0

Google Calendar MCP Server

A Model Context Protocol (MCP) server that provides Google Calendar integration through the Smithery framework. This server enables AI assistants to interact with Google Calendar data including calendars, events, and user authentication.

Features

  • OAuth 2.1 Authentication: Secure authentication using OAuth 2.1 with PKCE
  • Calendar Management: List, create, update, and delete calendars
  • Event Operations: Full CRUD operations for calendar events
  • Search Functionality: Search events across multiple calendars
  • All-day Event Support: Handle both timed and all-day events
  • Error Handling: Comprehensive error handling with user-friendly messages
  • Guest Access: Supports anonymous access for initial connections

Architecture

This project consists of two main components:

  1. MCP Server (src/): The main MCP server that implements the Model Context Protocol
  2. Auth Server (auth-server/): OAuth 2.1 authorization server for secure authentication

Prerequisites

  • Node.js 20.0.0 or higher
  • npm or yarn
  • Google Cloud Console project with Calendar API enabled
  • OAuth 2.0 credentials from Google Cloud Console

Installation

  1. Clone and navigate to the project

    cd gcal-mcp
npm install

  2. Install auth-server dependencies

    cd auth-server
npm install
cd ..

  3. Configure environment variables

    # Copy example files
cp auth-server/env.example auth-server/.env

# Edit auth-server/.env with your settings

Configuration

Auth Server Configuration

Create auth-server/.env with the following variables:

# Auth Server Configuration
AUTH_SERVER_ISSUER=http://localhost:3080
MCP_RESOURCE_ID=https://smithery.ai

# Google OAuth Configuration
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3080/oauth/google/callback

# JWT Configuration
JWT_SECRET=your_jwt_secret_key
JWT_ISSUER=http://localhost:3080
JWT_AUDIENCE=https://smithery.ai

# Database (optional - uses in-memory by default)
DATABASE_URL=sqlite://./auth.db

Google Cloud Console Setup

  1. Create a Google Cloud project
  2. Enable the Google Calendar API
  3. Configure OAuth consent screen
  4. Create OAuth 2.0 credentials
  5. Add authorized redirect URIs:
    • http://localhost:3080/oauth/google/callback
    • https://smithery.ai/playground/callback

Usage

Development Mode

  1. Start the auth server

    cd auth-server
npm run dev

  2. Start the MCP server (in a new terminal)

    cd gcal-mcp
npm run dev

  3. Connect via Smithery Playground

    • Open Smithery Playground
    • Connect to your MCP server
    • Complete OAuth authentication when prompted

Production Deployment

  1. Build the project

    npm run build

  2. Configure production environment

    • Update auth server URL in production
    • Use HTTPS for all URLs
    • Configure proper CORS settings

Available Tools

Calendar Tools

  • list_calendars: List all accessible calendars
  • get_calendar: Get details of a specific calendar
  • create_calendar: Create a new calendar
  • update_calendar: Update calendar properties
  • delete_calendar: Delete a calendar
  • search_calendars: Search calendars by name or description

Event Tools

  • list_events: List events from a calendar
  • get_event: Get details of a specific event
  • create_event: Create a new event
  • update_event: Update event properties
  • delete_event: Delete an event
  • search_events: Search events across calendars

Authentication Tools

  • check_auth_status: Check current authentication status

API Reference

Authentication Flow

  1. Initial Connection: MCP server allows anonymous initial connections
  2. OAuth Registration: Client registers with the auth server
  3. Authorization: User authorizes via Google OAuth
  4. Token Exchange: Authorization code exchanged for access token
  5. Token Verification: All subsequent requests verify the access token

Error Handling

The server provides comprehensive error handling with specific error types:

  • AuthenticationError: OAuth or token-related errors
  • ValidationError: Input validation failures
  • RateLimitError: Rate limiting violations
  • GoogleAPIError: Google Calendar API errors
  • NetworkError: Network connectivity issues

Development

Project Structure

gcal-mcp/
├── src/
│   ├── index.ts              # Main MCP server
│   ├── oauth-provider.ts     # OAuth provider implementation
│   ├── auth-utils.ts         # Authentication utilities
│   ├── constants.ts          # Server constants
│   ├── errors.ts             # Error handling
│   └── tools/
│       ├── auth.ts           # Authentication tools
│       ├── calendars.ts      # Calendar management tools
│       └── events.ts         # Event management tools
├── auth-server/
│   ├── src/
│   │   ├── index.ts          # Auth server main
│   │   ├── google-auth.ts    # Google OAuth integration
│   │   ├── storage.ts        # Token storage
│   │   └── crypto.ts         # Cryptographic utilities
│   └── tests/                # E2E tests
└── package.json

Scripts

  • npm run dev: Start development server
  • npm run build: Build for production
  • npm run check: Lint and format code
  • npm run test: Run tests

Testing

Run the comprehensive E2E tests:

cd auth-server
npm run test:e2e

Troubleshooting

Common Issues

  1. Infinite Loop During Registration

    • Cause: Smithery SDK's requireBearerAuth middleware blocks MCP initialize
    • Solution: OAuth is currently disabled. Contact Smithery developers for SDK fix

  2. Authentication Failures

    • Verify Google OAuth credentials
    • Check redirect URI configuration
    • Ensure Calendar API is enabled

  3. Network Connectivity

    • Verify auth server is running on port 3080
    • Check firewall settings
    • Ensure proper URL configuration

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm run dev

Configuration Check

Use the configuration checker:

./check-config.sh

Security Considerations

  • Token Storage: Access tokens are stored securely with automatic refresh
  • PKCE: Uses Proof Key for Code Exchange for enhanced security
  • HTTPS: Always use HTTPS in production
  • Scope Limitation: Minimal required scopes for Google Calendar access
  • Token Expiration: Automatic token refresh and cleanup

Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Add tests if applicable
  5. Run linting and formatting
  6. Submit a pull request

Code Style

  • Use TypeScript strict mode
  • Follow the existing code structure
  • Add comprehensive error handling
  • Include JSDoc comments for public APIs
  • Run npm run check before committing

Support

Related Projects