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
- check_availability - Check available appointment slots for a specific date and time range
- book_appointment - Book a new dental appointment
- cancel_appointment - Cancel an existing appointment
- reschedule_appointment - Reschedule an existing appointment
- get_appointments - Get appointments for a specific date range
- find_next_available - Find the next available appointment slot
Setup
Prerequisites
- Google Cloud Console project with Calendar API enabled
- OAuth 2.0 credentials configured
- Python 3.11+ (for local development)
Google Cloud Setup
- Go to Google Cloud Console
- Create a new project or select existing one
- Enable the Google Calendar API
- Go to "Credentials" and create OAuth 2.0 Client ID
- Configure OAuth consent screen
- 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 IDGOOGLE_CLIENT_SECRET- Your Google OAuth client secretGOOGLE_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
- Install dependencies:
pip install -r requirements.txt
-
Set up environment variables (see above)
-
Run the server:
python main.py
The server will be available at http://localhost:8000
Railway Deployment
- Connect your GitHub repository to Railway
- Set the environment variables in Railway dashboard
- Railway will automatically build and deploy using the Dockerfile
Railway Environment Variables
Set these in your Railway project dashboard:
GOOGLE_CLIENT_IDGOOGLE_CLIENT_SECRETGOOGLE_ACCESS_TOKENGOOGLE_REFRESH_TOKENGOOGLE_CALENDAR_ID(optional, defaults to 'primary')
API Endpoints
Health Check
GET /health- Simple health checkGET /status- Detailed status with service availability
MCP Tools
GET /tools- List available toolsPOST /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.
