# @ideadesignmedia/gcal-mcp
Private MCP server (stdio) and CLI for linking and operating multiple Google Calendar accounts. It stores tokens in a local SQLite database and can encrypt refresh tokens at rest with a user password.
The server speaks MCP over stdio and keeps stdout clean (JSON‑RPC only); all human‑readable logs go to stderr.
## Requirements
- Node.js >= 18.17
- A Google Cloud OAuth client (Web application) with Calendar API enabled
- You will need `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET`
## One‑liner (npx)
Use `npx` to run without installing globally. The package name is `@ideadesignmedia/gcal-mcp` and the binary is `gcal-mcp`.
```bash
# Help
npx -y @ideadesignmedia/gcal-mcp --help
# Link an account (prints an authorization URL)
npx -y @ideadesignmedia/gcal-mcp add \
--client-id "$GOOGLE_CLIENT_ID" \
--client-secret "$GOOGLE_CLIENT_SECRET"
# Lock the database (encrypts existing refresh tokens)
npx -y @ideadesignmedia/gcal-mcp passwd --pass 'your-strong-pass'
# Start the MCP server over stdio (stdout is JSON only)
GMAIL_MCP_DB_PASS='your-strong-pass' \
npx -y @ideadesignmedia/gcal-mcp start
```
## Database
- Default location: `~/.idm/gcal-mcp/db.sqlite`
- Override with `--db <path>` on any command
- When locked, refresh tokens are encrypted with AES‑GCM using a DEK derived from your password via scrypt
## Global Flags
- `--db <path>`: SQLite database path (defaults above)
- `--pass <pass>`: Database password (where applicable). For `start`, consider `GMAIL_MCP_DB_PASS` instead.
- `--read-only`: Start server with write tools disabled (create/update/delete)
Environment variables:
- `GMAIL_MCP_DB_PASS`: Password used by `start` (and as a fallback elsewhere)
- `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`: OAuth credentials (used by `add` if flags not supplied)
## Commands
- `start`
- Starts the MCP server over stdio
- Respects `--read-only`
- Stdout: JSON‑RPC messages only; logs to stderr
- Examples:
- `GMAIL_MCP_DB_PASS='...' npx -y @ideadesignmedia/gcal-mcp start`
- `add`
- Links a Google account and stores its refresh token
- Options:
- `--client-id <id>` / `--client-secret <secret>` (or use env vars)
- `--device` for Device Code flow (headless), otherwise uses loopback redirect and prints a URL to visit (default port 43112; change with `--listen-port <port>`)
- `--scopes <list>` to provide custom scopes (comma or space separated)
- `--choose-scopes` to interactively select calendar access (read-only vs read/write) and optionally add extra scopes
- Example:
- `npx -y @ideadesignmedia/gcal-mcp add --client-id $GOOGLE_CLIENT_ID --client-secret $GOOGLE_CLIENT_SECRET`
- `npx -y @ideadesignmedia/gcal-mcp add --choose-scopes --client-id $GOOGLE_CLIENT_ID --client-secret $GOOGLE_CLIENT_SECRET`
- `list`
- Lists linked accounts (id, email, display name, created)
- `remove <key>`
- Removes an account and its tokens by id or email
- `passwd`
- Locks the database or rotates an existing password
- Options:
- `--pass <pass>`: Password to set when locking, or new password when rotating
- `--rotate`: Rotate the existing password (requires `--old-pass`)
- `--old-pass <old>`: Old password for rotation
- `--hint <text>`: Optional password hint stored alongside the KDF parameters
## MCP Server Integration
Any MCP‑capable client can launch this server as a stdio process. A generic config entry looks like:
```json
{
"mcpServers": {
"gcal-mcp": {
"command": "npx",
"args": ["-y", "@ideadesignmedia/gcal-mcp", "start"],
"env": {
"GMAIL_MCP_DB_PASS": "${secret:GCAL_DB_PASS}",
"GOOGLE_CLIENT_ID": "${env:GOOGLE_CLIENT_ID}",
"GOOGLE_CLIENT_SECRET": "${env:GOOGLE_CLIENT_SECRET}"
}
}
}
}
```
Notes:
- The `start` command writes only JSON‑RPC to stdout as required by MCP stdio.
- Use your client’s secret storage for `GMAIL_MCP_DB_PASS` where available.
## Provided Tools
The server exposes the following tools. Names and parameter schemas follow the Chat Completions function tool shape.
Primary calendar only:
- All operations target the account’s primary calendar automatically; there is no `calendarId` parameter.
- This removes confusion between account vs calendar. The server passes `primary` internally.
Account resolution rules (applies wherever `account` is accepted):
- Accepts exact `email` or `id`.
- Also accepts a partial, case-insensitive match on email or display name.
- If `account` is omitted and exactly one account is linked, that account is used.
- If multiple accounts would match or are linked with no `account` provided, the tool throws a helpful error. Use `gcal-list_accounts` to choose deterministically.
- `gcal-list_accounts`
- Parameters: none
- Returns: `{ accounts: Array<{ id: string, email: string, displayName: string | null }> }`
- `gcal-resolve_account`
- Parameters:
- `query` (string; optional; email/id or partial). If omitted or blank, returns all accounts.
- Returns: `{ query: string, matches: Array<{ id: string, email: string, displayName: string | null }>, exact: boolean, ambiguous: boolean, count: number }`
- `gcal-search_events`
- Parameters:
- `account` (string; optional)
- `q` (string, optional)
- `timeMin` (ISO string, optional)
- `timeMax` (ISO string, optional)
- `maxResults` (integer 1..250, optional)
- Returns: `{ events: GoogleCalendarEvent[] }` (verbatim event objects)
- `gcal-get_event`
- Parameters:
- `account` (string; optional)
- `eventId` (string)
- Returns: `GoogleCalendarEvent`
- `gcal-create_event`
- Parameters:
- `account` (string; optional)
- `summary` (string)
- `description` (string, optional)
- `location` (string, optional)
- `start` (object: `{ dateTime?: string, date?: string, timeZone?: string }`)
- `end` (object: `{ dateTime?: string, date?: string, timeZone?: string }`)
- `attendees` (array of `{ email: string }`, optional)
- Returns: `GoogleCalendarEvent`
- `gcal-update_event`
- Parameters:
- `account` (string; optional)
- `eventId` (string)
- `patch` (object; partial event resource)
- Returns: `GoogleCalendarEvent`
- `gcal-delete_event`
- Parameters:
- `account` (string; optional)
- `eventId` (string)
- Returns: `{ ok: true }` on success
Read‑only mode:
- Start with `--read-only` to disable `gcal-create_event`, `gcal-update_event`, and `gcal-delete_event`.
## OAuth Flows
- Default: Loopback flow. The CLI opens your browser to grant access and listens on `127.0.0.1:43112` for the redirect (customizable via `--listen-port`).
- Headless: Device Code flow with `--device`. The CLI prints a code and verification URL to the terminal.
- Scopes used: `https://www.googleapis.com/auth/calendar`, plus `openid email profile` to capture account identity.
## Security Notes
- When locked, refresh tokens are encrypted at rest (AES‑GCM). The key is derived with scrypt using per‑DB salt and stored KDF parameters.
- The MCP `start` command emits no human‑readable output on stdout.
- Prefer setting `GMAIL_MCP_DB_PASS` via your MCP client’s secret system; avoid committing secrets in configs.
## Troubleshooting
- Database is locked
- Set `GMAIL_MCP_DB_PASS` or pass `--pass` when needed. For `start`, use the env var.
- OAuth did not return a refresh_token
- Ensure you used the provided `add` command (it requests offline access with consent). If you previously granted access without offline permission, remove prior consent in your Google Account or create a new OAuth client.
- Loopback callback failed
- Check firewall or try `--device` for Device Code flow.
- MCP client shows parse errors
- Verify you are launching the server with `start` and not another command. STDOUT must remain clean JSON‑RPC.
---
MIT © Idea Design Media
