Google Calendar MCP Server

MCP Server for the Google Calendar API, enabling Claude to interact with Google Calendar to manage events and find free time slots.

🚀 Quick Setup

For All

1. Download OAuth Credentials (2 minutes)

   • Go to Google Cloud Console (url은 1password의 'google calendar mcp google cloud url'를 참고)
   • Download the JSON file of 'Google Calendar MCP 용 데스크톱 클라이언트 1'

For Project Maintainers

2. Clone the Repository (1 minute)

   git clone https://github.com/TeamSparta-Inc/mcp.git
   cd mcp
   npm install

3. Run Setup Script (1 minute)

   cd src/google-calendar
   node setup-credentials.js /path/to/oauth-file.json

4. Configure Claude Desktop - Copy the config the script shows you

For Teammates

2. Run Setup Script (1 minute)

   npx @teamsparta/mcp-server-google-calendar gcalendar-setup /path/to/oauth-file.json

3. Configure Claude Desktop - Copy the config the script shows you

🎯 What You Can Do

Once set up, ask Claude to:

• Find free time across team calendars
• Schedule meetings with teammates
• Check availability before planning events
• Create/update/delete calendar events

Example Commands

"Find a 1-hour slot next week when me, [email protected], and [email protected] are all free"

"Schedule a team standup tomorrow at 10 AM with the whole team"

"What meetings do I have today?"

🔧 Available Tools

1. google_calendar_list_calendars - List all accessible calendars
2. google_calendar_list_events - List events from a specific calendar within a time range
3. google_calendar_fetch_event - Fetch details of a specific event
4. google_calendar_get_busy_times - Get busy time periods across multiple calendars
5. google_calendar_find_free_time - Find available time slots across multiple calendars
6. google_calendar_create_event - Create a new calendar event
7. google_calendar_update_event - Update an existing calendar event
8. google_calendar_delete_event - Delete a calendar event

Tool Examples

Find Free Time for Team Meetings

google_calendar_find_free_time({
  calendarIds: ["primary", "[email protected]", "[email protected]"],
  timeMin: "2024-01-15T09:00:00Z",
  timeMax: "2024-01-15T18:00:00Z",
  duration: 60,
});

Create Team Events

google_calendar_create_event({
  summary: "Team Standup",
  start: "2024-01-15T10:00:00+09:00",
  end: "2024-01-15T10:30:00+09:00",
  attendees: ["[email protected]", "[email protected]"],
  location: "Conference Room A",
});

Check Availability

google_calendar_get_busy_times({
  calendarIds: ["primary", "[email protected]"],
  timeMin: "2024-01-15T09:00:00Z",
  timeMax: "2024-01-15T18:00:00Z",
});

⚙️ Configuration

Claude Desktop Config

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@teamsparta/mcp-server-google-calendar"],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/path/to/gcalendar-server-credentials.json"
      }
    }
  }
}

Alternative: Individual Environment Variables

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["-y", "@teamsparta/mcp-server-google-calendar"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_ACCESS_TOKEN": "your-access-token",
        "GOOGLE_REFRESH_TOKEN": "your-refresh-token"
      }
    }
  }
}

🔄 Token Management

• Access tokens expire after ~1 hour
• Refresh tokens last much longer (months/years)
• Automatic refresh - The server automatically refreshes expired tokens
• Auto-save - Updated tokens are saved back to the credentials file
• One-time setup - Teammates rarely need to re-run setup

💡 Pro Tips

• Credentials file location: Put it somewhere permanent like ~/.config/ or ~/Documents/
• Calendar IDs: Use google_calendar_list_calendars to find available calendars
• Shared calendars: Calendar IDs are usually email addresses (e.g., [email protected])
• Time format: Use ISO 8601 format (2024-01-15T10:00:00+09:00)
• Timezone: Server uses Asia/Seoul timezone by default

🆘 Troubleshooting

Setup Issues

• Script fails: Make sure you downloaded OAuth credentials (not service account)
• File not found: Check the file path is correct
• Port in use: Wait a moment and try again

Authentication Errors

• Token expired: Re-run the setup script to refresh tokens
• Permission denied: Ensure OAuth app has calendar scope
• Credentials file: Make sure the path in your config is correct

Calendar Issues

• Calendar not found: Use list_calendars to verify calendar IDs
• No access: Make sure you have access to shared calendars
• Time format error: Use ISO 8601 format

Getting Calendar IDs

1. Use google_calendar_list_calendars to see all accessible calendars
2. For shared calendars, the ID is usually the email address
3. For resource calendars (meeting rooms), use the resource email

🐳 Docker Support

Build:

docker build -t mcp/google-calendar -f src/google-calendar/Dockerfile .

Run:

docker run -i --rm \
  -e GOOGLE_CREDENTIALS_PATH=/credentials.json \
  -v /path/to/credentials.json:/credentials.json \
  mcp/google-calendar

📋 Requirements

• Node.js 18+
• Google Cloud Project with Calendar API enabled
• OAuth 2.0 credentials

🌍 Cross-Platform

Works on:

• ✅ macOS
• ✅ Windows
• ✅ Linux

📄 License

MIT License - see LICENSE file for details.