@mcp-z/oauth-google

Docs: https://mcp-z.github.io/oauth-google OAuth client for Google APIs with multi-account support and PKCE.

Common uses

• Gmail/Drive/Sheets OAuth in MCP servers
• CLI and desktop OAuth flows
• Service account auth for server-to-server access
• DCR (self-hosted) for shared HTTP servers

Install

npm install @mcp-z/oauth-google keyv

Create a Google Cloud app

1. Go to Google Cloud Console.
2. Create or select a project.
3. Enable the API you need (Gmail, Drive, or Sheets).
4. Create OAuth 2.0 credentials (Desktop app).
5. Copy the Client ID and Client Secret.
6. Select your MCP transport (stdio for local and http for remote) and platform

• For stdio, choose "APIs & Services", + Create client, "Desktop app" type
• For http, choose "APIs & Services", + Create client, "Web application" type, add your URL (default is http://localhost:3000/oauth/callback based on the --port or PORT)
• For local hosting, add "http://127.0.0.1" for Ephemeral redirect URL

OAuth modes

Redirect URI modes (loopback)

• No REDIRECT_URI: ephemeral loopback (random port), works for stdio and http.
• REDIRECT_URI set: persistent callback /oauth/callback (HTTP only).

Loopback OAuth (interactive)

import { LoopbackOAuthProvider } from '@mcp-z/oauth-google';
import Keyv from 'keyv';
import { KeyvFile } from 'keyv-file';

const provider = new LoopbackOAuthProvider({
  service: 'gmail',
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  scope: 'https://www.googleapis.com/auth/gmail.modify',
  tokenStore: new Keyv({ store: new KeyvFile({ filename: '.tokens/google.json' }) })
});

Service account

import { ServiceAccountProvider } from '@mcp-z/oauth-google';

const provider = new ServiceAccountProvider({
  keyFilePath: '/path/to/service-account.json',
  scopes: ['https://www.googleapis.com/auth/drive']
});

DCR (self-hosted)

Use DcrOAuthProvider for bearer validation and createDcrRouter to host the DCR endpoints.

import { DcrOAuthProvider, createDcrRouter } from '@mcp-z/oauth-google';

const provider = new DcrOAuthProvider({
  clientId: process.env.GOOGLE_CLIENT_ID!,
  clientSecret: process.env.GOOGLE_CLIENT_SECRET!,
  scope: 'openid email profile',
  verifyEndpoint: 'https://your-host.com/oauth/verify'
});

const router = createDcrRouter({
  store,
  issuerUrl: 'https://your-host.com',
  baseUrl: 'https://your-host.com',
  scopesSupported: ['openid', 'email', 'profile'],
  clientConfig: {
    clientId: process.env.GOOGLE_CLIENT_ID!,
    clientSecret: process.env.GOOGLE_CLIENT_SECRET!
  }
});

Config helpers

Use parseConfig() and parseDcrConfig() to load CLI + env settings for servers.

Schemas and handler types

• schemas - Shared Zod schemas used by tools
• EnrichedExtra - Handler extra type with auth context

Requirements

• Node.js >= 22