GCAL

You can manage and operate multiple Google Calendar accounts securely from a private MCP server over stdio. It stores tokens locally, can encrypt refresh tokens at rest with a password, and exposes a set of calendar-related actions you can drive from any MCP-capable client.

How to use

Set up your MCP client to talk to this server over stdio. Start the server so it emits only JSON‑RPC messages on stdout and logs human‑readable information on stderr. Before starting, link your Google Calendar accounts with the add command, then perform actions like listing accounts, querying events, creating, updating, or deleting events. Start in non‑interactive mode if you want to run through an MCP client without manual prompts.

Key workflows you’ll typically perform:

• Link one or more Google accounts and store their refresh tokens securely.
• List linked accounts to identify the one you want to work with.
• Read events from a specific account and search for calendar events.
• Create, update, or delete events in the primary calendar of a chosen account (in read/write mode).
• Lock or rotate the database password to protect tokens at rest.

How to install

Prerequisites you need before installing and running the MCP server:

• Node.js 18.17 or newer
• A Google Cloud OAuth client (Web application) with Calendar API enabled
• Google client ID and secret (GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET)

Install and run using the one‑liner approach with npx. The server will start and listen for MCP stdio connections. Use the environment variable for the database password when starting.

# 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

Additional configuration and usage notes

The server keeps tokens in a local SQLite database by default. You can override the database path with the --db option anytime you run a command. When locked, refresh tokens are encrypted with AES‑GCM using a key derived from your password via scrypt.

Environment variables you’ll commonly use:

Available tools

gcal-list_accounts

Returns a list of linked accounts with id, email, and display name for deterministic selection.

gcal-resolve_account

Resolves an account query to a specific account or returns a set of matches with details like id, email, and displayName.

gcal-search_events

Searches events for an account with optional query, time range, and maxResults, returning the matching events.

gcal-get_event

Fetches a single event by eventId for an account.

gcal-create_event

Creates a new event in the account's primary calendar with provided details like summary, start, end, attendees, etc.

gcal-update_event

Updates an existing event identified by eventId with a provided patch.

gcal-delete_event

Deletes an event by eventId for the specified account and returns { ok: true } on success.