This example demonstrates how to create safe, read-only MCP tools that interact with Google Calendar using the MXCP OAuth authentication system with the Google Calendar API.

Features Demonstrated

1. MXCP OAuth Authentication

Project-wide Google OAuth configuration
Automatic token management through MXCP authentication system
User authentication via standard OAuth 2.0 flow
Error handling for authentication failures

2. Google Calendar API Integration (Read-Only)

whoami - Display information about the current authenticated Google user
list_calendars - Retrieve all accessible calendars with filtering options
get_calendar - Get detailed information for a specific calendar
list_events - List events from a calendar with time filtering and pagination
get_event - Retrieve detailed information for a specific event
search_events - Search for events matching text queries
get_freebusy - Check availability across multiple calendars
Token-based API access using authenticated user context
Safe Design: Only read operations - no calendar or event modifications

Prerequisites

Google Account: You need a Google account with Calendar access
Google Cloud Project: Create a project in Google Cloud Console with Calendar API enabled
OAuth Credentials: Create OAuth 2.0 credentials for your application
Python Dependencies: The google-api-python-client and related libraries (automatically managed by MXCP)

Setup

1. Create Google Cloud Project and Enable APIs

Go to the Google Cloud Console
Create a new project or select an existing one
Enable the Google Calendar API:
- Go to APIs & Services → Library
- Search for "Google Calendar API"
- Click on it and press Enable

In Google Cloud Console, go to APIs & Services → OAuth consent screen
Configure the consent screen:
- User Type: External (for testing) or Internal (for organization use)
- App Name: "MXCP Google Calendar Integration" (or your preferred name)
- User Support Email: Your email
- Developer Contact: Your email
Add Scopes (under "Data access" section):
- Click "Add or Remove Scopes"
- In the scope selection dialog, search for "calendar"
- Find and select https://www.googleapis.com/auth/calendar.readonly (Calendar read-only access)
- Click "Update" to save the scopes
Save the consent screen configuration

Note: The scopes are configured in the OAuth Consent Screen, not when creating the Client ID. This is why you don't see scope options when creating credentials.

3. Create OAuth 2.0 Client ID

Go to APIs & Services → Credentials
Click Create Credentials → OAuth 2.0 Client IDs
Configure the client:
- Application Type: Web application
- Name: "MXCP Calendar Client" (or your preferred name)
- Authorized Redirect URIs: Add based on your deployment:
  - Local Development: http://localhost:8000/google/callback
  - Remote/Production: https://your-domain.com/google/callback (replace with your actual server URL)
Save and note down the Client ID and Client Secret

4. Configure Environment Variables

Set your Google OAuth credentials:

export GOOGLE_CLIENT_ID="your-client-id-from-google-cloud"
export GOOGLE_CLIENT_SECRET="your-client-secret-from-google-cloud"

5. Configure Callback URL for Your Deployment

The callback URL configuration depends on where your MXCP server will run:

Local Development

For local development, the default configuration in config.yml uses http://localhost:8000/google/callback. This works when:

You're running MXCP locally on your development machine
Users authenticate from the same machine where MXCP is running

Remote/Production Deployment

For remote servers or production deployments, you need to:

Update config.yml: Modify the callback URL:

redirect_uris:
  - "https://your-domain.com/google/callback"  # Your actual URL

Update base_url: Set the correct base URL in your config:

transport:
  http:
    base_url: https://your-domain.com  # Your actual server URL

Configure OAuth Credentials: Add the production callback URL to your Google Cloud OAuth credentials

Important:

The callback URL must be accessible from the user's browser, not just from your server
For production deployments, Google requires HTTPS for callback URLs
You can configure multiple callback URLs in your OAuth credentials to support both local development and production

Project Structure

google-calendar/
├── mxcp-site.yml              # Project metadata
├── config.yml                 # Server and authentication configuration
├── python/                    # Python modules
│   └── google_calendar_client.py  # Google Calendar API implementations
├── tools/                     # Tool definitions (read-only)
│   ├── whoami.yml             # Current user information
│   ├── list_calendars.yml     # List accessible calendars
│   ├── get_calendar.yml       # Get calendar details
│   ├── list_events.yml        # List calendar events
│   ├── get_event.yml          # Get event details
│   ├── search_events.yml      # Search for events
│   └── get_freebusy.yml       # Check availability
└── README.md                  # This file

Key Concepts

MXCP OAuth Integration: Uses MXCP's built-in Google OAuth provider for secure authentication
User Context: Access tokens are automatically managed and provided through get_user_context()
Token-based Authentication: Google API client is initialized with OAuth tokens instead of service account credentials
Project-wide Configuration: Authentication is configured at the project level in config.yml
Error Handling: Comprehensive error handling for authentication and API failures
Type Safety: Uses Python type hints and comprehensive error handling for data validation

Running the Example

Once you've completed the setup above:

Start MXCP:

# From the examples/google-calendar directory:
MXCP_CONFIG=config.yml mxcp serve

Connect your MCP client (e.g., Claude Desktop) to the MXCP server
Authenticate: When the client first connects, you'll be redirected to Google to authorize the application
Use the tools: Once authenticated, you can use all the Google Calendar tools through your MCP client

Example Usage

When you use the tools through an MCP client, you can:

Get User Information

Use the whoami tool to see your Google profile information

Manage Calendars

List all your calendars, get details for specific calendars, and check which ones you can modify

View Calendar Events

- List events: "What's on my calendar this week?"
- Search events: "Find all meetings with John"
- Get event details: "Show me details for my 3 PM meeting"
- View event information: "What meetings do I have with the marketing team?"

Check Availability

Use the freebusy tool to find available time slots across multiple calendars

Troubleshooting

Authentication Errors

"No user context available": User needs to authenticate first by running mxcp serve and completing OAuth flow
"No Google access token found": Authentication was incomplete or token expired - re-authenticate
OAuth Credentials Issues: Verify your GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are correct
Callback URL Mismatch: Ensure the callback URL in your Google Cloud OAuth credentials matches where your MXCP server is accessible
API Not Enabled: Make sure the Google Calendar API is enabled in your Google Cloud project

API Errors

403 Forbidden: Check that the Calendar API is enabled and your OAuth scopes include calendar access
404 Not Found: Verify calendar IDs and event IDs are correct and accessible to the authenticated user
Rate Limiting: Google Calendar API has rate limits - implement appropriate retry logic if needed

OAuth Setup Issues

Consent Screen: Make sure your OAuth consent screen is properly configured with the correct scopes
Redirect URI: The redirect URI must exactly match your MXCP server's accessible address
Scopes: Ensure your OAuth configuration includes https://www.googleapis.com/auth/calendar.readonly scope

Next Steps

This example demonstrates a comprehensive set of read-only Google Calendar integration tools. You could extend it with additional features like:

Advanced calendar filtering and search capabilities
Integration with other Google Workspace services (read-only)
Calendar analytics and reporting
Event pattern analysis and insights
Multi-calendar comparison and availability analysis

Note: This example is intentionally read-only for safety. If you need write operations (create, update, delete), you would need to:

Change the OAuth scope to https://www.googleapis.com/auth/calendar (full access)
Add appropriate write functions with proper validation and error handling
Implement additional safety measures and user confirmations

README.md

Google Calendar OAuth Demo (Read-Only)