npm package: @oppie-ai/mcp-google-calendar
Description: Google Calendar MCP Server with extensive support for calendar management
Author: nspady
Latest version: 0.0.1

# Google Calendar MCP Server

[![npm version](https://img.shields.io/npm/v/@oppie-ai/mcp-google-calendar)](https://www.npmjs.com/package/@oppie-ai/mcp-google-calendar)
[![Docker Image](https://img.shields.io/docker/v/oppieai/mcp-google-calendar)](https://hub.docker.com/r/oppieai/mcp-google-calendar)
[![GitHub](https://img.shields.io/github/stars/OppieAI/google-calendar-mcp)](https://github.com/OppieAI/google-calendar-mcp)

A Model Context Protocol (MCP) server that provides Google Calendar integration for AI assistants like Claude.

## Features

- **Multi-Calendar Support**: List events from multiple calendars simultaneously
- **Event Management**: Create, update, delete, and search calendar events
- **Recurring Events**: Advanced modification capabilities for recurring events
- **Free/Busy Queries**: Check availability across calendars
- **Smart Scheduling**: Natural language understanding for dates and times
- **Intelligent Import**: Add calendar events from images, PDFs or web links

## Authentication

This MCP server uses external token authentication. You need to provide:
1. A valid Google OAuth2 access token
2. The granted scopes for that token

### For stdio mode (Claude Desktop):
- Set `OPPIE_ACCESS_TOKEN` environment variable with your Google OAuth access token
- Set `OPPIE_GRANTED_SCOPES` environment variable with the granted scopes

### For HTTP mode:
- Send `x-env-oppie-access-token` header with your Google OAuth access token  
- Send `x-env-oppie-granted-scopes` header with the granted scopes

Scopes can be provided in any of these formats:
- JSON array: `["https://www.googleapis.com/auth/calendar", "https://www.googleapis.com/auth/calendar.events"]`
- Space-separated: `https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events`
- Comma-separated: `https://www.googleapis.com/auth/calendar,https://www.googleapis.com/auth/calendar.events`

## Quick Start

### Option 1: Use with Claude Desktop (stdio mode)

Add to your Claude Desktop configuration:

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

```json
{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@oppie-ai/mcp-google-calendar"],
      "env": {
        "OPPIE_ACCESS_TOKEN": "your-google-oauth-access-token",
        "OPPIE_GRANTED_SCOPES": "https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events"
      }
    }
  }
}
```

### Option 2: Local Installation

```bash
git clone https://github.com/OppieAI/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build

# For stdio mode:
export OPPIE_ACCESS_TOKEN="your-google-oauth-access-token"
export OPPIE_GRANTED_SCOPES="https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events"
npm start

# For HTTP mode (default):
npm start
# Server will run on http://localhost:8080
# Send required headers with each request
```

### Option 3: Docker Installation (HTTP mode)

```bash
# Using Docker Hub image
docker run -p 8080:8080 oppieai/mcp-google-calendar

# Or build locally
git clone https://github.com/OppieAI/google-calendar-mcp.git
cd google-calendar-mcp
docker compose up
```

The Docker container runs in HTTP mode on port 8080. You must include authentication headers with each request:
- `x-env-oppie-access-token`: Your Google OAuth access token
- `x-env-oppie-granted-scopes`: The granted scopes

Example:
```bash
curl -X POST http://localhost:8080 \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-env-oppie-access-token: your-token" \
  -H "x-env-oppie-granted-scopes: https://www.googleapis.com/auth/calendar https://www.googleapis.com/auth/calendar.events" \
  -d '{"jsonrpc":"2.0","method":"tools/list","params":{},"id":1}'
```

## Available Tools

### Calendar Management
- `list-calendars` - List all calendars
- `list-colors` - List available calendar colors

### Event Operations
- `list-events` - List events with flexible filtering
  - Multiple calendar support
  - Time range filtering
  - Timezone handling
- `search-events` - Full-text search across events
- `create-event` - Create new events with:
  - All-day or timed events
  - Recurring events
  - Attendees and notifications
  - Video conferencing
- `update-event` - Update existing events
- `delete-event` - Delete events (with recurring event options)

### Scheduling
- `free-busy` - Check availability across calendars
- `get-current-time` - Get current time in any timezone

### Import Events
- `add-event-from-image` - Extract and create events from images
- `add-event-from-pdf` - Extract and create events from PDFs
- `add-event-from-url` - Create events from web content

## Development

### Running Tests
```bash
npm test                    # Unit tests
npm run test:integration    # Integration tests
```

### Debug Mode
```bash
# Enable debug logging
DEBUG=true npm start

# Or in Docker
docker run -p 8080:8080 -e DEBUG=true oppieai/mcp-google-calendar
```

### HTTP Mode Endpoints
- `GET /health` - Health check endpoint
- `POST /` - MCP protocol endpoint (requires authentication headers)

## Configuration

### Environment Variables
- `OPPIE_ACCESS_TOKEN` - Google OAuth access token (stdio mode)
- `OPPIE_GRANTED_SCOPES` - Granted OAuth scopes (stdio mode)
- `DEBUG` - Enable debug logging (true/false)
- `TRANSPORT` - Transport mode: `stdio` or `http` (default: http)
- `PORT` - HTTP server port (default: 8080)
- `HOST` - HTTP server host (default: 127.0.0.1)

### Docker Configuration
The Docker setup always runs in HTTP mode. Configure via environment variables:
```yaml
environment:
  DEBUG: true
  PORT: 8080
  HOST: 0.0.0.0
```

## Troubleshooting

### Authentication Issues
- Ensure your access token is valid and not expired
- Verify the token has the required calendar scopes
- Check that headers are being sent correctly (for HTTP mode)

### Connection Issues
- For HTTP mode: Check that the Accept header includes both `application/json` and `text/event-stream`
- Verify the server is running on the expected port
- Check firewall/network settings

### Debug Logging
Enable debug mode to see detailed logs:
```bash
DEBUG=true npm start
```

## License

MIT License - see LICENSE file for details