@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.

# 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:

{
  "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