Google Calendar MCP Server

A Model Context Protocol (MCP) server for managing dental appointments through Google Calendar. Built specifically for Railway deployment with clean, production-ready code.

Features

• Appointment Management: Book, cancel, and reschedule dental appointments
• Availability Checking: Check available time slots for specific dates
• Calendar Integration: Full Google Calendar API integration
• MCP Protocol: Compatible with MCP clients and AI assistants
• Railway Ready: Optimized for Railway deployment

Available Tools

1. check_availability - Check available appointment slots for a specific date and time range
2. book_appointment - Book a new dental appointment
3. cancel_appointment - Cancel an existing appointment
4. reschedule_appointment - Reschedule an existing appointment
5. get_appointments - Get appointments for a specific date range
6. find_next_available - Find the next available appointment slot

Setup

Prerequisites

1. Google Cloud Console project with Calendar API enabled
2. OAuth 2.0 credentials configured
3. Python 3.11+ (for local development)

Google Cloud Setup

1. Go to Google Cloud Console
2. Create a new project or select existing one
3. Enable the Google Calendar API
4. Go to "Credentials" and create OAuth 2.0 Client ID
5. Configure OAuth consent screen
6. Download the credentials JSON file

Environment Variables

Copy env.example to .env and fill in your credentials:

cp env.example .env

Required environment variables:

• GOOGLE_CLIENT_ID - Your Google OAuth client ID
• GOOGLE_CLIENT_SECRET - Your Google OAuth client secret
• GOOGLE_ACCESS_TOKEN - OAuth access token (obtained through OAuth flow)
• GOOGLE_REFRESH_TOKEN - OAuth refresh token (obtained through OAuth flow)
• GOOGLE_CALENDAR_ID - Calendar ID (use 'primary' for main calendar)
• PORT - Server port (default: 8000)

OAuth Token Generation

To get the access and refresh tokens, you'll need to run the OAuth flow. Here's a simple script to help:

from google_auth_oauthlib.flow import InstalledAppFlow
from google.auth.transport.requests import Request
import pickle
import os

SCOPES = ['https://www.googleapis.com/auth/calendar']

def get_credentials():
    creds = None
    if os.path.exists('token.pickle'):
        with open('token.pickle', 'rb') as token:
            creds = pickle.load(token)
    
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'credentials.json', SCOPES)
            creds = flow.run_local_server(port=0)
        
        with open('token.pickle', 'wb') as token:
            pickle.dump(creds, token)
    
    print(f"Access Token: {creds.token}")
    print(f"Refresh Token: {creds.refresh_token}")
    print(f"Client ID: {creds.client_id}")
    print(f"Client Secret: {creds.client_secret}")

if __name__ == '__main__':
    get_credentials()

Local Development

1. Install dependencies:

pip install -r requirements.txt

2. Set up environment variables (see above)

3. Run the server:

python main.py

The server will be available at http://localhost:8000

Railway Deployment

1. Connect your GitHub repository to Railway
2. Set the environment variables in Railway dashboard
3. Railway will automatically build and deploy using the Dockerfile

Railway Environment Variables

Set these in your Railway project dashboard:

• GOOGLE_CLIENT_ID
• GOOGLE_CLIENT_SECRET
• GOOGLE_ACCESS_TOKEN
• GOOGLE_REFRESH_TOKEN
• GOOGLE_CALENDAR_ID (optional, defaults to 'primary')

API Endpoints

Health Check

• GET /health - Simple health check
• GET /status - Detailed status with service availability

MCP Tools

• GET /tools - List available tools
• POST /tools - Execute tool calls

Example Tool Call

curl -X POST "https://your-railway-app.railway.app/tools" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "check_availability",
    "params": {
      "date": "2024-01-15",
      "start_time": "09:00",
      "end_time": "17:00",
      "duration": 60
    }
  }'

Project Structure

dental-calendar-mcp-clean/
├── main.py              # Main FastAPI application
├── requirements.txt     # Python dependencies
├── Dockerfile          # Docker configuration
├── railway.json        # Railway deployment config
├── env.example         # Environment variables template
└── README.md           # This file

Error Handling

The server includes comprehensive error handling:

• OAuth credential validation
• Google Calendar API error handling
• Input validation for all tool parameters
• Proper HTTP status codes and error messages

Security Notes

• Never commit OAuth credentials to version control
• Use environment variables for all sensitive data
• The server includes CORS middleware for web integration
• All API endpoints are properly validated

License

This project is open source and available under the MIT License.