yt-gmail-mcp

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

Tools

Gmail

Google Drive

Google Calendar

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)

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 :::3000 during re-auth

The OAuth callback listener needs port 3000 (or your GMAIL_MCP_OAUTH_PORT). Kill whatever is on that port, or set GMAIL_MCP_OAUTH_PORT to a free port.

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.

License

MIT