@mcp-z/mcp-gmail

@mcp-z/mcp-gmail

Docs: https://mcp-z.github.io/mcp-gmail Gmail MCP server for searching, reading, and sending mail over MCP.

Common uses

• Search and read messages
• Send and reply to emails
• Manage labels and export messages to CSV

Transports

MCP supports stdio and HTTP.

Stdio

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-gmail"]
    }
  }
}

HTTP

{
  "mcpServers": {
    "gmail": {
      "type": "http",
      "url": "http://localhost:9002/mcp",
      "start": {
        "command": "npx",
        "args": ["-y", "@mcp-z/mcp-gmail", "--port=9002"]
      }
    }
  }
}

start is an extension used by npx @mcp-z/cli up to launch HTTP servers for you.

Create a Google Cloud app

• Go to Google Cloud Console.
• Create or select a project.
• Enable the Gmail API.
• Create OAuth 2.0 credentials (Desktop app).
• Copy the Client ID and Client Secret.
• 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

• Enable OAuth2 scopes: openid https://www.googleapis.com/auth/userinfo.profile https://www.googleapis.com/auth/userinfo.email https://mail.google.com/
• Add test emails

OAuth modes

Configure via environment variables or the env block in .mcp.json. See server.json for the full list of options.

Loopback OAuth (default)

Environment variables:

GOOGLE_CLIENT_ID=your-client-id
GOOGLE_CLIENT_SECRET=your-client-secret

Example (stdio) - Create .mcp.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-gmail"],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id"
      }
    }
  }
}

Example (http) - Create .mcp.json:

{
  "mcpServers": {
    "outlook": {
      "type": "http",
      "url": "http://localhost:3000",
      "start": {
        "command": "npx",
        "args": ["-y", "@mcp-z/mcp-gmail", "--port=3000"],
        "env": {
          "GOOGLE_CLIENT_ID": "your-client-id"
        }
      }
    }
  }
}

Local (default): omit REDIRECT_URI → ephemeral loopback. Cloud: set REDIRECT_URI to your public /oauth/callback and expose the service publicly.

Note: start block is a helper in "npx @mcp-z/cli up" for starting an http server from your .mpc.json. See @mcp-z/cli for details.

Service account

Environment variables:

AUTH_MODE=service-account
GOOGLE_SERVICE_ACCOUNT_KEY_FILE=/path/to/service-account.json

Example:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "@mcp-z/mcp-gmail", "--auth=service-account"],
      "env": {
        "GOOGLE_SERVICE_ACCOUNT_KEY_FILE": "/path/to/service-account.json"
      }
    }
  }
}

DCR (self-hosted)

HTTP only. Requires a public base URL. CSV export and /files are disabled in DCR mode; resourceStoreUri is ignored.

{
  "mcpServers": {
    "gmail-dcr": {
      "command": "npx",
      "args": [
        "-y",
        "@mcp-z/mcp-gmail",
        "--auth=dcr",
        "--port=3456",
        "--base-url=https://oauth.example.com"
      ],
      "env": {
        "GOOGLE_CLIENT_ID": "your-client-id",
        "GOOGLE_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

How to use

# List tools
mcp-z inspect --servers gmail --tools

# Call a tool
mcp-z call gmail message-search '{"query":"from:[e-mail]"}'

Tools

• categories-list
• label-add
• label-delete
• labels-list
• message-get
• message-mark-read
• message-move-to-trash
• message-respond
• message-search
• message-send
• messages-export-csv

Resources

• email

Prompts

• draft-email
• query-syntax

Configuration reference

See server.json for all supported environment variables, CLI arguments, and defaults.