# Google Calendar MCP Server

An MCP (Model Context Protocol) server for managing Google Calendar reminders with support for time-based and location-based triggers.

## Features

- **Time-based reminders**: "Remind me tomorrow at 9am to call mom"
- **Location-based reminders**: "Remind me to go to store X when I'm near Hashalom street in Tel Aviv"
- **List reminders**: View upcoming reminders
- **Delete reminders**: Remove reminders by ID

## Prerequisites

- Python 3.11+
- [uv](https://github.com/astral-sh/uv) package manager
- Google Cloud project with Calendar API enabled

## Setup

### 1. Install dependencies

```bash
uv sync
```

### 2. Set up Google Cloud credentials

1. Go to [Google Cloud Console](https://console.cloud.google.com/)
2. Create a new project or select an existing one
3. Enable the **Google Calendar API**:
   - Go to "APIs & Services" > "Library"
   - Search for "Google Calendar API"
   - Click "Enable"
4. Create OAuth 2.0 credentials:
   - Go to "APIs & Services" > "Credentials"
   - Click "Create Credentials" > "OAuth client ID"
   - Choose "Desktop app" as the application type
   - Download the credentials JSON file
5. Save the credentials file:
   ```bash
   mkdir -p ~/.config/gcalendar-mcp
   mv ~/Downloads/client_secret_*.json ~/.config/gcalendar-mcp/credentials.json
   ```

### 3. First-time authentication

Run the server once to authenticate:

```bash
uv run gcalendar-mcp
```

This will open a browser window for Google OAuth. After authorizing, your credentials will be saved.

## Usage with Claude Code

Add to your Claude Code MCP configuration (`~/.claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "gcalendar": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/gcalendar_mcp", "gcalendar-mcp"]
    }
  }
}
```

## Available Tools

### create_time_reminder

Create a time-based reminder.

**Parameters:**
- `title` (required): What to be reminded about
- `time` (required): When to remind (natural language supported)
- `description` (optional): Additional notes

**Examples:**
- "remind me tomorrow at 9 to call mom"
- "remind me in 2 hours to take a break"
- "remind me today at 3pm to join the meeting"

### create_location_reminder

Create a location-based reminder.

**Parameters:**
- `title` (required): What to be reminded about
- `location` (required): The location/address
- `description` (optional): Additional notes
- `date` (optional): Date for the reminder

**Examples:**
- "remind me to buy milk when near the grocery store"
- "remind me to go to store X when I'm near Hashalom street in Tel Aviv"

**Note:** Google Calendar doesn't natively support location-based triggers. This creates an event with the location noted. For automatic location notifications, use Google Maps or a dedicated location reminder app.

### list_reminders

List upcoming reminders from the calendar.

**Parameters:**
- `max_results` (optional): Maximum number of results (default: 10)

### delete_reminder

Delete a reminder by its event ID.

**Parameters:**
- `event_id` (required): The ID of the event to delete

## Configuration

You can customize the credentials directory by setting the environment variable:

```bash
export GCALENDAR_MCP_CONFIG_DIR=/path/to/custom/config
```

## Development

```bash
# Install dev dependencies
uv sync --dev

# Run tests
uv run pytest
```

## License

MIT