gmcp

🔗
gmcp

MCP server for Gmail and Google Calendar integration.
by @johnie

Overview

GMCP is a Model Context Protocol server that enables LLMs to interact with Gmail and Google Calendar. It provides tools for searching emails, managing labels, sending messages, and working with calendar events—all through secure OAuth2 authentication.

Installation

NPM (Recommended)

# Install globally
npm install -g gmcp

# Or run directly
npx gmcp
bunx gmcp

Docker

docker pull johnie/gmcp:latest

From Source

git clone https://github.com/johnie/gmcp.git
cd gmcp
bun install

Quick Start

1. Google Cloud Setup

• Create a project in Google Cloud Console
• Enable Gmail API and Calendar API
• Create OAuth 2.0 Client ID (Desktop Application type)
• Download the credentials JSON file

2. Authenticate

# If installed globally
gmcp auth

# Or with npx
npx gmcp auth

# Or from source
bun run auth

Follow the prompts to authorize. The browser will show "connection refused" after authorization - this is expected. Copy the code= parameter from the URL.

3. Run

# Globally installed
gmcp start
# or just: gmcp

# With npx
npx gmcp start

# From source
bun run start

Claude Desktop Integration

Using npx (Recommended)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmcp": {
      "command": "npx",
      "args": ["-y", "gmcp"],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/path/to/token.json",
        "GOOGLE_SCOPES": "gmail.readonly,gmail.send,calendar.events"
      }
    }
  }
}

Using Docker

{
  "mcpServers": {
    "gmcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-v", "/path/to/credentials.json:/app/data/credentials.json:ro",
        "-v", "/path/to/token.json:/app/data/token.json",
        "-e", "GOOGLE_CREDENTIALS_PATH=/app/data/credentials.json",
        "-e", "GOOGLE_TOKEN_PATH=/app/data/token.json",
        "-e", "GOOGLE_SCOPES=gmail.readonly,gmail.send,calendar.events",
        "johnie/gmcp:latest"
      ]
    }
  }
}

Using Bun (From Source)

{
  "mcpServers": {
    "gmcp": {
      "command": "bun",
      "args": ["run", "/path/to/gmcp/src/cli.ts"],
      "env": {
        "GOOGLE_CREDENTIALS_PATH": "/path/to/credentials.json",
        "GOOGLE_TOKEN_PATH": "/path/to/token.json",
        "GOOGLE_SCOPES": "gmail.readonly,gmail.send,calendar.events"
      }
    }
  }
}

Tools

Gmail (17 tools)

Tool	Description
gmcp_gmail_search_emails	Search with Gmail query syntax
gmcp_gmail_get_email	Get message by ID
gmcp_gmail_get_thread	Get conversation thread
gmcp_gmail_list_attachments	List attachments on message
gmcp_gmail_get_attachment	Download attachment data
gmcp_gmail_send_email	Send new email
gmcp_gmail_reply	Reply to email in thread
gmcp_gmail_create_draft	Create draft message
gmcp_gmail_delete_email	Permanently delete email (bypasses trash)
gmcp_gmail_archive_email	Archive email (remove from inbox)
gmcp_gmail_list_labels	List all labels
gmcp_gmail_get_label	Get label details
gmcp_gmail_create_label	Create custom label
gmcp_gmail_update_label	Update label settings
gmcp_gmail_delete_label	Delete custom label
gmcp_gmail_modify_labels	Add/remove labels on message
gmcp_gmail_batch_modify	Batch label operations

Calendar (4 tools)

Tool	Description
gmcp_calendar_list_calendars	List all calendars
gmcp_calendar_list_events	List events with filters
gmcp_calendar_get_event	Get event by ID
gmcp_calendar_create_event	Create event (supports recurring, Google Meet)

Configuration

Environment Variables

Variable	Description
GOOGLE_CREDENTIALS_PATH	Path to OAuth2 credentials JSON
GOOGLE_TOKEN_PATH	Path to store OAuth2 tokens
GOOGLE_SCOPES	Comma-separated API scopes

Scopes

Scope	Access
gmail.readonly	Read emails and labels
gmail.send	Send emails
gmail.modify	Read, modify labels, delete emails
gmail.labels	Manage labels
gmail.compose	Create drafts and send
calendar.readonly	Read calendars and events
calendar.events	Manage events
calendar	Full calendar access

Examples:

# Read-only
GOOGLE_SCOPES=gmail.readonly,calendar.readonly

# Full access
GOOGLE_SCOPES=gmail.readonly,gmail.modify,gmail.send,calendar.events

CLI Reference

gmcp [command]

Commands:
  start    Start MCP server (default)
  auth     Run OAuth2 authentication flow

Options:
  --help, -h       Show usage
  --version, -v    Show version

Testing

bunx @modelcontextprotocol/inspector bun run start

License

MIT