yt-gmail-mcp

MCP server for Gmail, Google Drive, Google Calendar, and Google Tasks — search, read, send, and manage threads, files, events, and to-dos.

Implements the Model Context Protocol specification: it runs over the stdio transport, speaks JSON-RPC 2.0, negotiates the protocol version on initialize, advertises tools capabilities, and describes each tool with a JSON Schema. Protocol version negotiation is handled by the @modelcontextprotocol/sdk Server class, which defaults to the latest supported version.

Tools

Gmail

Google Drive

Google Calendar

Google Tasks

Related MCP server: Google-Workspace-MCP-Server

Setup

1. Google Cloud Console

1. Go to Google Cloud Console

2. Create a project (or use an existing one)

3. Enable the APIs you need:

   • Gmail API

   • Google Drive API (if using Drive tools)

   • Google Calendar API (if using Calendar tools)

   • Google Tasks API (if using Tasks tools)

4. Create an OAuth 2.0 Client ID of type Desktop application

5. Add http://localhost:3000/oauth2callback as an authorized redirect URI

6. Download the client configuration JSON

2. Place the credentials

Save the downloaded JSON as ~/.gmail-mcp/gcp-oauth.keys.json:

mkdir -p ~/.gmail-mcp
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/gcp-oauth.keys.json

3. Authenticate

npx yt-gmail-mcp auth

This opens a browser where you sign in with your Google account. On success, tokens are saved to ~/.gmail-mcp/credentials.json.

Configuration

Custom port

If port 3000 is occupied:

GMAIL_MCP_OAUTH_PORT=3001 npx yt-gmail-mcp auth

Make sure your GCP OAuth client's redirect URI matches.

MCP host config

opencode

{
  "mcp": {
    "gmail": {
      "type": "local",
      "command": ["npx", "yt-gmail-mcp"]
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["yt-gmail-mcp"]
    }
  }
}

Troubleshooting

Tools disappear mid-session

If the MCP host starts while OAuth tokens are expired, the server fails to initialize and doesn't register tools. Fix:

1. Run npx yt-gmail-mcp auth to refresh credentials

2. Restart the MCP host

EADDRINUSE during re-auth

The OAuth callback listener starts on port 3000 (or your GMAIL_MCP_OAUTH_PORT). For installed (Desktop) credentials it now automatically retries on the next free port if it's taken, so this should rarely surface. web credentials require the redirect URI to exactly match a registered value, so they don't fall back — there, register the port you use or set GMAIL_MCP_OAUTH_PORT to a registered free port.

Batching tools triggers multiple re-auth flows

Concurrent auth-requiring calls (e.g. Gmail + Calendar + Tasks) now share a single re-auth flow: the first failure opens the browser and the others wait and retry once it completes. To avoid orphaning a browser tab, call auth_status first to preflight credential health before batching.

invalid_grant / expired tokens

OAuth refresh tokens for unverified Testing-mode apps expire after 7 days. Run npx yt-gmail-mcp auth to re-authenticate. For production, publish your OAuth app through Google's verification process.

Re-auth succeeds but Tasks calls fail

If re-auth completed but Tasks tools still error, the Tasks API itself may be disabled in the GCP project. Enable it at:

https://console.developers.google.com/apis/api/tasks.googleapis.com/overview?project=496352139179

It can take a minute to propagate — retry after enabling.

License

MIT