oswaldslabbert/gmail-mcp repository overview

⁠Gmail MCP for cursor / claude etc.

⁠Authentication

1. Create a Google Cloud Project and obtain credentials:

   a. Create a Google Cloud Project:

   • Go to Google Cloud Console⁠
   • Create a new project or select an existing one
   • Enable the Gmail API for your project

   b. Create OAuth 2.0 Credentials:

   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose either "Desktop app" or "Web application" as application type
   • Give it a name and click "Create"
   • For Web application, add http://localhost:3000/oauth2callback to the authorized redirect URIs
   • Download the JSON file of your client's OAuth keys
   • Rename the key file to gcp-oauth.keys.json

2. Run Authentication:

   You can authenticate in two ways:

   a. Global Authentication (Recommended):

   # First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
   mkdir -p ~/.gmail-mcp
   mv gcp-oauth.keys.json ~/.gmail-mcp/
   
   # Run authentication from anywhere
   npx @gongrzhe/server-gmail-autoauth-mcp auth
   

   Copy

   b. Local Authentication:

   # Place gcp-oauth.keys.json in your current directory
   # The file will be automatically copied to global config
   npx @gongrzhe/server-gmail-autoauth-mcp auth
   

   Copy

   The authentication process will:

   • Look for gcp-oauth.keys.json in the current directory or ~/.gmail-mcp/
   • If found in current directory, copy it to ~/.gmail-mcp/
   • Open your default browser for Google authentication
   • Save credentials as ~/.gmail-mcp/credentials.json

⁠Authenticate with docker

docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth

⁠Usage

• Add the following to your mcp.json
• In Claude you will find it in settings > Developer
• In Cursor you will find it in settings > Tools & MCP

⁠Important

Map a common downloads folder between all your MCP server, that they can share fils between the servers

{
    "mcpServers": {
        "gmail": {
            "command": "docker",
            "args": [
                "run",
                "-i",
                "--rm",
                "-v",
                "<path to user folder>/.gmail-mcp:/gmail-server",
                "-v",
                "<path to your downloads folder>:Downloads",
                "-e",
                "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
                "-e",
                "GMAIL_OAUTH_PATH=/gmail-server/gcp-oauth.keys.json",
                "oswaldslabbert/gmail-mcp"
            ]
        }
    }
}