@kresnayulianta/google-mcp

A self-hosted Model Context Protocol (MCP) server for Google Workspace — Gmail, Google Calendar, Google Maps, and Scheduler. Uses OAuth 2.0 for authentication.

Note: Requires a Google Cloud project with OAuth 2.0 credentials. Run google-mcp connect <profile> once to authenticate before use.

Features

Gmail

| Tool | Description | |------|-------------| | google_gmail_search | Search Gmail with query string | | google_gmail_get_message | Get full email content | | google_gmail_send | Send an email | | google_gmail_reply | Reply to an email thread | | google_gmail_trash | Move email to trash | | google_gmail_label | Apply labels to email |

Google Calendar

| Tool | Description | |------|-------------| | google_calendar_list_calendars | List all calendars | | google_calendar_list_events | List events from a calendar | | google_calendar_list_events_multi | Query multiple calendars at once | | google_calendar_create_event | Create event (supports recurring via RRULE) | | google_calendar_update_event | Update existing event | | google_calendar_delete_event | Delete an event |

Google Maps

| Tool | Description | |------|-------------| | google_maps_compute_route | Compute driving route and travel time | | google_maps_geocode | Convert address to coordinates |

Scheduler

| Tool | Description | |------|-------------| | google_scheduler_create | Schedule a recurring task | | google_scheduler_list | List scheduled tasks |

Requirements

• Node.js 20+
• A Google Cloud project with:
  • OAuth 2.0 credentials (Desktop app type)
  • APIs enabled: Gmail API, Google Calendar API, Google Maps API
• Docker (recommended for deployment)

Setup

1. Google Cloud Project

1. Create a project at console.cloud.google.com
2. Enable the required APIs:
   • Gmail API
   • Google Calendar API
   • Maps Routes API
3. Create OAuth 2.0 credentials (Desktop application type)
4. Download the credentials JSON

2. Configuration

# google-mcp.config.yaml
server:
  name: google-mcp
  version: 1.0.0

profiles:
  - key: personal
    email_hint: [email protected]
    client_id: your-client-id.apps.googleusercontent.com
    client_secret: your-client-secret
    scopes:
      - https://www.googleapis.com/auth/gmail.modify
      - https://www.googleapis.com/auth/calendar
      - https://www.googleapis.com/auth/contacts.readonly

3. OAuth Authentication

Run once per profile to authorize access. This opens a browser for Google's OAuth consent screen and saves a refresh token to ~/.config/google-mcp/tokens/<profile>.json.

# via npx
npx @kresnayulianta/google-mcp connect personal

# or locally after npm install
npm run connect:profile -- personal

4. Run

# via npx
npx @kresnayulianta/google-mcp

# Development
npm run dev

# Docker
docker compose up google-mcp -d

Usage with Claude

Step 1 — One-time auth setup

GOOGLE_CLIENT_ID=xxx GOOGLE_CLIENT_SECRET=yyy \
  npx @kresnayulianta/google-mcp connect personal

Token will be saved to ~/.config/google-mcp/tokens/personal.json and reused on every subsequent run.

Step 2 — Add to your client

Claude Desktop

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google": {
      "command": "npx",
      "args": ["-y", "@kresnayulianta/google-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_MAPS_API_KEY": "your-maps-api-key"
      }
    }
  }
}

Cursor

Add to ~/.cursor/mcp.json (global) or .cursor/mcp.json (per project):

{
  "mcpServers": {
    "google": {
      "command": "npx",
      "args": ["-y", "@kresnayulianta/google-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id.apps.googleusercontent.com",
        "GOOGLE_CLIENT_SECRET": "your-client-secret",
        "GOOGLE_MAPS_API_KEY": "your-maps-api-key"
      }
    }
  }
}

Claude Code

claude mcp add google -- npx -y @kresnayulianta/google-mcp

Then set the required env vars in your shell or .env file.

Environment Variables

MCP_HTTP_PORT=3001            # HTTP server port (default: 3001)
GOOGLE_MCP_CONFIG=./google-mcp.config.yaml
GOOGLE_MAPS_API_KEY=your-key  # Required for Maps tools
MCP_API_KEY=your-secret       # Optional: lock server with API key

HTTP Authentication

| Header | Purpose | |--------|---------| | Authorization: Bearer key | MCP server access key (requires MCP_API_KEY) |

URL params:

http://localhost:3001/mcp?profile=personal

License

MIT