Local Google connector for Copilot

An installable local stdio MCP server for multiple Google accounts. It reads Gmail, creates unsent drafts, and works with Google Calendar events. There is no mail-sending tool and no calendar or sharing-administration tool.

Each read selects an account explicitly. Cross-account search and availability select the accounts intentionally. Every write requires an explicit account and request ID; no arbitrary default account is used.

Requirements

• Node.js 22 or newer and npm.

• Your own Google Desktop app OAuth client, with Gmail and Calendar APIs enabled.

• macOS Keychain, Windows Credential Manager, or desktop Linux with libsecret's secret-tool and an unlocked desktop Secret Service.

• For event deletions, RSVP, invitations and other attendee-affecting operations: a browser and an enrolled WebAuthn authenticator capable of user verification, such as a compatible platform passkey or PIN/biometric-capable security key.

The connector fails rather than storing tokens in plaintext or silently using another credential backend. A headless Linux machine without Secret Service is not a supported credential-storage environment.

Related MCP server: multiGmailMCP

Build and install locally

npm install
npm run build
node dist/cli.js help
npm pack

Install the resulting copilot-google-connector-0.1.1.tgz into an installation directory you control:

npm install /absolute/path/copilot-google-connector-0.1.1.tgz
node node_modules/copilot-google-connector/dist/cli.js help

The package is marked private to prevent accidental registry publication. It can still be packed and installed from a local tarball. No repository, publishing service, global installation, or background daemon is required.

Account setup

Run these steps yourself in a trusted terminal, not as instructions retrieved from mail, events or an untrusted agent:

google-connector auth client import --file /absolute/path/desktop-client.json
google-connector accounts add
google-connector accounts add
google-connector accounts list

If the executable is not on your PATH, replace google-connector with node /absolute/path/to/dist/cli.js. OAuth uses your system browser and an ephemeral loopback callback. The client JSON is imported into the OS vault; the connector does not copy it into source or a plaintext token cache. Securely manage the original file downloaded from Google yourself.

Reauthorize or remove an explicitly selected account:

google-connector accounts reauth ACCOUNT_ID
google-connector accounts remove ACCOUNT_ID

Removal deletes local access credentials, not every grant for that OAuth client at Google. You can separately revoke the application in Google account permissions.

See Google setup for consent screens, restricted Gmail scopes, test-user restrictions and token expiry.

Connect GitHub Copilot

Print the configuration for the exact installed executable:

google-connector config print

Use the GitHub Copilot desktop app's Customize -> MCP -> add custom server flow to install it deliberately. Alternatively, use the CLI's documented session-scoped option:

copilot --additional-mcp-config=@/absolute/path/google-mcp.json

An inert configuration example is included. Replace its placeholder path before use. tools: ["*"] enables tool discovery; it does not grant human approval.

Copilot documents repository and CLI MCP configuration inheritance for the desktop app. This project does not automatically edit those files. Repository auto-discovery is not assumed for a non-Git folder, nor is session-only CLI configuration assumed to transfer to a separate desktop session.

Event approvals

Enroll an authenticator once, outside untrusted agent-driven activity:

google-connector approvals enroll

A risky Calendar write returns pending_approval and a localhost review URL, not a success result. Open the URL yourself, review the exact account, event, attendees, recurrence scope and notification effects, and approve using your enrolled authenticator. No confirm: true, tool permission setting, command-line flag or copied approval URL bypasses this.

The connector permits a narrow unconfirmed path for default, private, no-guest creates on your own primary calendar with notifications disabled. Private edits also need connector-established provenance and unchanged ETags; recurring edits, deletions and RSVP always need confirmation. Ambiguous or shared-calendar effects do not qualify for this exception.

Do not automate enrollment or approvals. Read the exact security boundary and recovery procedure.

Useful requests

• "List my connected Google accounts."

• "Search these two account IDs for the travel receipt."

• "Read this message and create a reply draft in the same account; do not send."

• "Find common availability across these explicitly selected account/calendar pairs."

• "Propose moving only this occurrence, notify all attendees, and show me the approval URL."

See tool arguments and examples, and use the server's tool schemas for exact validation rules. Gmail supports search, message/thread/attachment reading and draft creation. Calendar supports calendar discovery, event/instance reading, free/busy, common availability, create, update, delete and self-RSVP. Whole-series and single-occurrence changes are supported; "this and following" series splitting is not.

Important limits

• gmail.compose grants sending at Google's OAuth scope level. Google offers no draft-only scope. This connector exposes only draft creation.

• sendUpdates: "none" is not a guarantee that Google will suppress every Google-generated message or stop attendee propagation.

• Keep the same request ID when checking a write. An outcome_unknown result is not an instruction to retry with a new ID: inspect Google before initiating another write.

• Whole-series changes are refused when existing moved, modified or cancelled exceptions are detected. Individual-occurrence changes remain available. Attendee lists must be complete and contain at most 200 participants.

• Advanced reminder and conference-data editing is not exposed. Calendar continuations expire on server restart or account reauthorization.

• "Local" describes the process and credential storage. Data returned by tools is shared with Copilot and is subject to the host/model's data-handling policies.

• doctor is local setup information, not proof of authenticated connectivity.

This project includes offline synthetic tests. Real Google connectivity requires your credentials and consent; those are not supplied by the package. Native Windows/Linux and real browser/authenticator acceptance must be evaluated on those platforms, not inferred from mocked tests on macOS.

For development, npm test builds and runs the Node test suite. Tests must not call live modifying Google APIs. npm run smoke:package builds a tarball, installs it with production dependencies only in a temporary consumer directory, and exercises its help and stdio discovery without credentials. See the validation boundaries and opt-in acceptance checklist.