my-google-workspace-mcp

Google Workspace MCP server with local Desktop OAuth + PKCE. This project is forked from the Apache-2.0 licensed Google Workspace extension.

The Gmail REST implementation and MCP tools from upstream are retained. This fork removes the Cloud Function and Secret Manager OAuth proxy: authorization codes and refresh tokens are exchanged directly with Google by the local MCP process, and tokens remain on the user's machine.

Prerequisites

• Node.js 20 or newer.
• A Google Cloud OAuth client whose application type is Desktop app.
• The Google Workspace APIs used by the enabled tools must be enabled in the same Google Cloud project.
• The OAuth consent screen and test/published users must be configured for that project.

Do not use a Web application OAuth client. Desktop clients support loopback redirects such as http://127.0.0.1:<random-port>/oauth2callback.

Run as an MCP server

Provide the Desktop OAuth client at process launch:

GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com" \
GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret" \
npx -y @laylzj777/my-google-workspace-mcp

Example stdio MCP configuration:

{
  "mcpServers": {
    "google-workspace": {
      "command": "npx",
      "args": ["-y", "@laylzj777/my-google-workspace-mcp"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_OAUTH_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

This makes the client ID and client secret dynamic configuration values. A desktop host can collect them in an install/authorization dialog and inject them into the MCP process environment; there is no built-in default client in the manifest or package.

On the first tool call, the server starts a loopback callback listener and opens Google's consent page. The OAuth request uses PKCE (S256) and a random state value. After consent, the local process exchanges the authorization code and saves the token locally.

Explicit login

You can authorize before starting the MCP server:

GOOGLE_OAUTH_CLIENT_ID="your-client-id.apps.googleusercontent.com" \
GOOGLE_OAUTH_CLIENT_SECRET="your-client-secret" \
npx -y -p @laylzj777/my-google-workspace-mcp my-google-workspace-login

Use --force to replace existing credentials. The browser must be able to reach the loopback address on the machine running the command. For SSH or containers, set a fixed OAUTH_CALLBACK_PORT and forward that port.

Configuration

| Environment variable | Required | Purpose | | -------------------------------------------- | -------- | ---------------------------------------------------------- | | GOOGLE_OAUTH_CLIENT_ID | Yes | Google Cloud Desktop OAuth client ID. | | GOOGLE_OAUTH_CLIENT_SECRET | Yes | Google Cloud Desktop OAuth client secret. | | OAUTH_CALLBACK_HOST | No | 127.0.0.1 by default; localhost is also allowed. | | OAUTH_CALLBACK_PORT | No | Fixed loopback port; an ephemeral port is used by default. | | MY_GOOGLE_WORKSPACE_MCP_CONFIG_DIR | No | Overrides the local token/config directory. | | MY_GOOGLE_WORKSPACE_MCP_FORCE_FILE_STORAGE | No | Set to true to skip the OS keychain. | | WORKSPACE_FEATURE_OVERRIDES | No | Enables/disables upstream tool feature groups. |

The legacy aliases WORKSPACE_CLIENT_ID, GOOGLE_CLIENT_ID, WORKSPACE_CLIENT_SECRET, and GOOGLE_CLIENT_SECRET are accepted, but the GOOGLE_OAUTH_* names are recommended.

Local token storage

The server first attempts the operating system keychain under the service name my-google-workspace-mcp-oauth. If no keychain is available, it stores an AES-256-GCM encrypted token file and a local master key in:

~/.config/my-google-workspace-mcp/

Both fallback files use restrictive permissions. No token, client secret, or authorization code is sent to a project-owned Cloud Function.

Tools

This fork retains the upstream Gmail REST service and Gmail MCP tools, including search, message/thread retrieval, labels, drafts, send, reply, archive, trash, and attachment operations. The other upstream Workspace services and MCP tools are retained as well; see tool documentation.

Development

npm install
npm test
npm run build
npm pack --dry-run

Security

Workspace tools can read and mutate sensitive account data. Review tool calls and treat email/document content as untrusted input because it may contain indirect prompt injection instructions.

License

Apache-2.0. See LICENSE. Original Google LLC copyright and license headers are retained in forked source files.