📅 Google Calendar MCP Server

A powerful Model Context Protocol (MCP) server that lets Claude interact with your Google Calendar seamlessly!

Transform Claude into your personal calendar assistant with full Google Calendar integration. Create meetings, check schedules, manage events, and more - all through natural conversation with Claude.

🌟 What Can This Do?

✨ Smart Calendar Management

📋 View all your calendars - See every calendar you have access to
📅 Check your schedule - Get today's events or upcoming events for any timeframe
🎯 Create meetings instantly - Set up Google Meet events with attendees
❌ Cancel events - Remove events you no longer need
🔍 Search events - Find events within specific date ranges

🤖 Claude Integration Examples

Ask Claude things like:

"What meetings do I have today?"
"Schedule a team standup for tomorrow at 10 AM with the engineering team"
"Cancel my 3 PM meeting on Friday"
"What's my schedule looking like next week?"
"Create a Google Meet for our client review next Tuesday"

🚀 Quick Start

Step 1: Prerequisites

Python 3.8 or higher
A Google account with Calendar access
Nango account for authentication (handles Google OAuth for you)

Step 2: Installation

# Clone or download the MCP server files
git clone <your-repo-url>
cd google-calendar-mcp

# Install required packages
uv sync

Step 3: Set Up Environment Variables

Create a .env file in the project directory:

# Copy the example file
cp .env.example .env

Edit .env with your Nango credentials:

# Required Nango Configuration
NANGO_NANGO_BASE_URL=https://api.nango.dev
NANGO_NANGO_SECRET_KEY=your_nango_secret_key_here 
NANGO_CONNECTION_ID=your_connection_id_here
NANGO_INTEGRATION_ID=your_integration_id_here

🔧 Need help with Nango setup? Check the Nango Setup Guide below!

Step 4: Configure Claude Desktop

Add this configuration to your Claude Desktop settings:

On macOS: ~/Library/Application Support/Claude/claude_desktop_config.json On Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "uvx",
      "args": ["git+https://github.com/Shameerpc5029/google-calendar-mcp.git"],
      "env": {
        "NANGO_NANGO_BASE_URL": "https://api.nango.dev",
        "NANGO_NANGO_SECRET_KEY": "your_nango_secret_key_here",
        "NANGO_CONNECTION_ID": "your_connection_id_here", 
        "NANGO_INTEGRATION_ID": "your_integration_id_here"
      }
    }
  }
}

Step 5: Test It Out!

Restart Claude Desktop completely
Start a new conversation with Claude
Ask Claude: "What meetings do I have today?"

If everything is set up correctly, Claude will be able to access your Google Calendar! 🎉

🛠️ Available Tools

Tool	Description	Example Use
`get_all_calendars`	List all your Google Calendars	"Show me all my calendars"
`get_calendar_events`	Get events from a specific calendar	"What's on my work calendar this week?"
`create_meet_event`	Create a new event with Google Meet	"Schedule a team meeting for Friday at 2 PM"
`cancel_calendar_event`	Delete/cancel an event	"Cancel my 3 PM meeting today"
`get_today_events`	Get today's events	"What's my schedule today?"
`get_upcoming_events`	Get upcoming events	"What do I have coming up next week?"

🔧 Nango Setup Guide

Nango handles the complex Google OAuth flow for you. Here's how to set it up:

1. Create a Nango Account

Go to Nango.dev and sign up
Create a new project

2. Set Up Google Calendar Integration

In your Nango dashboard, add a new integration
Choose "Google Calendar" as the provider
Follow Nango's guide to configure Google OAuth credentials

3. Get Your Credentials

NANGO_SECRET_KEY: Found in your Nango project settings
NANGO_CONNECTION_ID: Created when a user connects their Google account
NANGO_INTEGRATION_ID: The ID of your Google Calendar integration

4. Test Your Connection

# Test that your environment is set up correctly
python -c "import os; print('✅ All env vars set!' if all([os.getenv('NANGO_CONNECTION_ID'), os.getenv('NANGO_INTEGRATION_ID'), os.getenv('NANGO_NANGO_SECRET_KEY')]) else '❌ Missing env vars')"

🧪 Testing Your Setup

Option 1: Test with MCP Inspector

# Install the MCP inspector
npm install -g @modelcontextprotocol/inspector

# Test your server
npx @modelcontextprotocol/inspector python main.py

Option 2: Direct Python Test

# Run the server directly to see if it starts without errors
python main.py

Option 3: Test with Claude

Ask Claude: "Can you check what calendar tools are available?"

🔍 Troubleshooting

Common Issues

❌ "Failed to retrieve calendars"

Check your Nango credentials in .env
Verify your Google Calendar connection in Nango dashboard
Ensure the Google account has calendar access

❌ "NANGO_CONNECTION_ID environment variable is required"

Make sure your .env file is in the same directory as the Python script
Check that all environment variables are set correctly
Restart Claude Desktop after making changes

❌ Claude can't find the calendar tools

Verify the full path in your Claude config is correct
Make sure you restarted Claude Desktop completely
Check the Claude Desktop logs for error messages

Getting Help

Check the logs: Claude Desktop shows MCP server logs in its developer console
Test your .env: Run python -c "from dotenv import load_dotenv; load_dotenv(); import os; print(os.environ.get('NANGO_CONNECTION_ID'))"
Verify file paths: Make sure all paths in your Claude config are absolute paths

📋 Example Usage with Claude

Once set up, you can have natural conversations with Claude about your calendar:

You: "What's my schedule looking like today?"

Claude: I'll check your calendar for today's events.

{
  "success": true,
  "events": [
    {
      "summary": "Team Standup",
      "start": "2024-01-15T09:00:00Z",
      "end": "2024-01-15T09:30:00Z"
    }
  ],
  "total_events": 1
}

You have 1 event today: Team Standup from 9:00 AM to 9:30 AM.

You: "Schedule a client meeting for next Friday at 2 PM with john@company.com"

Claude: I'll create that meeting for you with a Google Meet link.

{
  "success": true,
  "event": {
    "summary": "Client Meeting",
    "start": "2024-01-19T14:00:00Z",
    "attendees": [{"email": "john@company.com"}]
  }
}

✅ Created "Client Meeting" for Friday, January 19th at 2:00 PM with john@company.com. Google Meet link has been included automatically.

🔐 Security & Privacy

Your credentials: Stored locally in your .env file - never shared
Google access: Managed through Nango's secure OAuth flow
Data handling: All calendar data stays between your Google account, Nango, and Claude
No data storage: This MCP server doesn't store any of your calendar information

🤝 Contributing

Found a bug or want to add a feature?

Fork the repository
Create a feature branch
Make your changes
Test thoroughly
Submit a pull request

📄 License

MIT License - feel free to use this in your own projects!

🎉 Enjoy your new AI-powered calendar assistant!

If you found this helpful, consider starring the repository and sharing it with others who might benefit from AI calendar management.