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

   bash

   cd gcal-mcp
   npm install
   

2. Install auth-server dependencies

   bash

   cd auth-server
   npm install
   cd ..
   

3. Configure environment variables

   bash

   # 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

   bash

   cd auth-server
   npm run dev
   

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

   bash

   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

   bash

   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

• Issues: Report bugs via GitHub Issues
• Documentation: Smithery Docs
• Community: Smithery Discord

Related Projects

• Smithery CLI
• Model Context Protocol
• Google APIs Node.js Client