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:
- MCP Server (
src/): The main MCP server that implements the Model Context Protocol - 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
-
Clone and navigate to the project
cd gcal-mcp npm install -
Install auth-server dependencies
cd auth-server npm install cd .. -
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
- Create a Google Cloud project
- Enable the Google Calendar API
- Configure OAuth consent screen
- Create OAuth 2.0 credentials
- Add authorized redirect URIs:
http://localhost:3080/oauth/google/callbackhttps://smithery.ai/playground/callback
Usage
Development Mode
-
Start the auth server
cd auth-server npm run dev -
Start the MCP server (in a new terminal)
cd gcal-mcp npm run dev -
Connect via Smithery Playground
- Open Smithery Playground
- Connect to your MCP server
- Complete OAuth authentication when prompted
Production Deployment
-
Build the project
npm run build -
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
- Initial Connection: MCP server allows anonymous initial connections
- OAuth Registration: Client registers with the auth server
- Authorization: User authorizes via Google OAuth
- Token Exchange: Authorization code exchanged for access token
- 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 servernpm run build: Build for productionnpm run check: Lint and format codenpm run test: Run tests
Testing
Run the comprehensive E2E tests:
cd auth-server
npm run test:e2e
Troubleshooting
Common Issues
-
Infinite Loop During Registration
- Cause: Smithery SDK's requireBearerAuth middleware blocks MCP initialize
- Solution: OAuth is currently disabled. Contact Smithery developers for SDK fix
-
Authentication Failures
- Verify Google OAuth credentials
- Check redirect URI configuration
- Ensure Calendar API is enabled
-
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
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- Run linting and formatting
- 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 checkbefore committing
Support
- Issues: Report bugs via GitHub Issues
- Documentation: Smithery Docs
- Community: Smithery Discord