# GCAL-MCP
A Dedalus MCP server for read-only access to the Google Calendar API v3.
## Setup
1. Create Google OAuth credentials (one-time)
- Go to the [Google Cloud Console](https://console.cloud.google.com)
- Create/select a project
- Enable **Google Calendar API**
- Configure **OAuth consent screen**
- If in testing mode: add your Google account as a **Test user**
- Create an **OAuth client ID**
- Application type: **Desktop app**
- Download the JSON (OAuth client credentials)
2. Copy `.env.example` to `.env` and set your credentials path:
```
GOOGLE_OAUTH_CREDENTIALS=/absolute/path/to/your/oauth-client.json
```
3. Install dependencies:
```bash
uv sync
```
4. Authenticate once (opens browser and stores tokens locally):
```bash
uv run python -m src.gcal_auth
```
5. Run the server:
```bash
uv run python -m src.main
```
## Available Tools
### Calendars
- `gcal_list_calendars` - List all calendars accessible by the user
- `gcal_get_calendar` - Get details of a specific calendar
### Events
- `gcal_list_events` - List events from a calendar with date filtering
- `gcal_get_event` - Get details of a specific event by ID
- `gcal_search_events` - Search events by text query
- `gcal_get_event_instances` - Get instances of a recurring event
### Free/Busy
- `gcal_get_freebusy` - Query free/busy information for calendars
### Settings
- `gcal_get_settings` - Get user's calendar settings
- `gcal_get_setting` - Get a specific calendar setting
### Colors
- `gcal_get_colors` - Get available calendar and event colors
## Authentication
This server uses **Google OAuth Bearer tokens**. Recommended flow:
- Provide your OAuth client JSON via `GOOGLE_OAUTH_CREDENTIALS`
- Run `uv run python -m src.gcal_auth` once
- Tokens will be saved to `~/.config/gcal-mcp/tokens.json` (configurable) and **auto-refreshed**
**Note:** This provides read-only access to calendar data. Write operations (creating, updating, deleting events) are not currently supported in this read-only implementation.
### Getting an Access Token
`gcal-mcp` will obtain and refresh access tokens for you via the installed-app OAuth flow.
If you need the exact scope(s), default is:
- `https://www.googleapis.com/auth/calendar.readonly`
### Token Refresh
Access tokens expire (typically after ~1 hour) but this repo will refresh them automatically if a refresh token was issued.
If you ever need to re-authenticate, run:
```bash
uv run python -m src.gcal_auth
```
### Relevant environment variables
- `GOOGLE_OAUTH_CREDENTIALS`: Path to downloaded OAuth client JSON (**Desktop app**)
- `GCAL_TOKEN_PATH` (optional): Token file location (default `~/.config/gcal-mcp/tokens.json`)
- `GCAL_SCOPES` (optional): Comma-separated scopes (default is read-only)
- `GCAL_ACCESS_TOKEN` (optional/manual): If set, overrides all other auth logic
## API Rate Limits
Google Calendar API has quota limits. See [Google Calendar API Quotas](https://developers.google.com/calendar/api/guides/quota) for details.
Default limits:
- 1,000,000 queries per day
- 500 queries per 100 seconds per user
## Example Usage
### List all calendars
```python
result = await client.call_tool("gcal_list_calendars", {})
```
### List events for the next week
```python
from datetime import datetime, timedelta
now = datetime.utcnow()
week_later = now + timedelta(days=7)
result = await client.call_tool("gcal_list_events", {
"calendar_id": "primary",
"time_min": now.isoformat() + "Z",
"time_max": week_later.isoformat() + "Z",
})
```
### Search for events
```python
result = await client.call_tool("gcal_search_events", {
"query": "meeting",
"calendar_id": "primary",
})
```
### Check availability
```python
result = await client.call_tool("gcal_get_freebusy", {
"time_min": "2024-01-15T00:00:00Z",
"time_max": "2024-01-15T23:59:59Z",
"calendar_ids": ["primary", "work@example.com"],
})
```
## License
MIT
