docs/mcp/gmail_mcp_gcp_setup.md

Gmail MCP – GCP Setup (Terraform + Bash)

This folder provisions the minimum GCP infrastructure to run the Gmail MCP server without requiring billing:

• Creates (or adopts) a GCP project
• Enables gmail.googleapis.com
• Grants your user:
• roles/editor
• roles/serviceusage.serviceUsageAdmin Prints console links to finish OAuth (consent screen + Desktop client)

  Billing is not required for Gmail API or OAuth Desktop client.

Prerequisites

• Terraform ≥ 1.6
• gcloud (optional but useful for verifying/importing projects)
• A Google account (you'll also add it as a Test user on the OAuth consent screen)

Files

• versions.tf – provider & Terraform version pins
• providers.tf – Google provider config (uses project_id and region)
• variables.tf – input variables
• main.tf – project, Gmail API enablement, IAM bindings
• outputs.tf – project IDs and console URLs
• terraform.tfvars – team defaults (simple key = "value" pairs)

Example terraform.tfvars:

project_id   = "gradio-hackathon-25"
project_name = "Gradio Agent MCP Hackathon 25"
user_email   = "hr.cjordan.agent.hack.winter25@gmail.com"
# region    = "europe-west3" # optional

*Quick Start (recommended: use the scripts)

From the repo root:

1. Authenticate gcloud + ADC

chmod +x scripts/gcp_setup.sh
./scripts/gcp_setup.sh

2. Apply Terraform with smart defaults + auto-import

chmod +x scripts/terraform_apply.sh
./scripts/terraform_apply.sh

• The script prompts for project_id, project_name, user_email.
• Press Enter to use defaults from terraform/terraform.tfvars.
• If the project already exists, it is auto-imported to avoid 409 alreadyExists.

---

Manual Usage (alternative)

Run these from this terraform/ directory:

terraform init

# If the project already exists, import it so Terraform manages it:
# terraform import google_project.project <your-project-id>

terraform apply

Override values:

terraform apply \
  -var="project_id=my-mcp-project" \
  -var="project_name=My MCP Project" \
  -var="user_email=you@example.com"

Or via env vars:

export TF_VAR_project_id="my-mcp-project"
export TF_VAR_project_name="My MCP Project"
export TF_VAR_user_email="you@example.com"
terraform apply

Outputs

• project_id / project_number
• gmail_api_service — "gmail.googleapis.com" (resource present ⇒ enabled)
• console_oauth_consent_screen_url — configure consent (External, Test user, add scope)
• console_oauth_credentials_url — create OAuth 2.0 Client ID (Desktop app)

Final OAuth Setup (one-time, in Console)

Terraform cannot create the OAuth consent screen or Desktop OAuth client, so you'll do these two steps once in the Google Cloud Console.
This setup allows your local Gmail MCP server to access Gmail via OAuth securely.

💡 Tip: In the new Google Cloud UI, the old “Scopes” and “Test users” tabs are now under Data access and Audience in the left sidebar.

---

1️⃣ Configure the OAuth Consent Screen

Purpose: Identify your app to Google and specify who can use it during testing.

1. Open the link printed in Terraform outputs:
   → console_oauth_consent_screen_url

2. If prompted, choose User type: External, then click Create.

3. Fill out App info:

   • App name: Gmail MCP Local
   • User support email: your Gmail address
   • Developer contact email: your Gmail address
   • Click Save and Continue

4. In the left sidebar, go to Data access

   • Click Add or remove scopes
   • Add the following scopes:

     https://www.googleapis.com/auth/gmail.modify
     openid
     https://www.googleapis.com/auth/userinfo.email
     

     ✅ These provide read, send, and modify access — no extra Gmail scopes required.

5. Go to Audience (left sidebar)

   • Under Test users, click Add users
   • Add your Gmail account address
   • Click Save

6. Go to Summary and confirm:

   • User type → External
   • Publishing status → Testing
   • Test users → your Gmail account
   • Scopes → shows Gmail modify, openid, userinfo.email

---

2️⃣ Create a Desktop OAuth Client

Purpose: This provides the credentials your local MCP server uses to initiate the OAuth flow.

1. Open the second Terraform output link:
   → console_oauth_credentials_url

2. Click Create credentials → OAuth client ID

3. Choose:

   • Application type: Desktop app
   • Name: gmail-mcp-desktop

4. Click Create, then Download JSON, and move it into the expected directory:

mkdir -p ~/.gmail-mcp
mv ~/Downloads/client_secret_*.json ~/.gmail-mcp/credentials.json

⚠️ Important: Two Different JSONs

• The file from:

gcloud auth application-default login

is your Application Default Credentials (ADC) — used by Terraform and gcloud. It is not the same as the Desktop OAuth client JSON. The Gmail MCP server requires the Desktop OAuth client JSON you downloaded. → Place it at ~/.gmail-mcp/credentials.json.

🚀 When You Run the MCP Server

The server will open a browser window asking you to sign in and approve access. You'll see your app name (Gmail MCP Local) and the Gmail modify scope. After approving, tokens are cached locally (usually ~/.gmail-mcp/token.json), so you won't need to approve again.

---

⚙️ Install Required Tools

Before testing or running the Gmail MCP server, make sure the following tools are installed:

🟣 1. Install uv

uv is a fast Python package manager used to run the Gmail MCP server.

Check if it's already installed:

uv --version

If not, install it:

curl -LsSf https://astral.sh/uv/install.sh | sh

Verify:

uv --version

🟠 2. Install Node.js (includes npm and npx)

npx is used to run the MCP Inspector, which lets you test your Gmail MCP server locally.

brew install node

🧪 Testing Locally with MCP Inspector

Once toBefore connecting to Claude Desktop or a LangGraph agent, you can visually inspect and test your Gmail MCP server using the MCP Inspector web UI.

1️⃣ Run with simple path (direct server entry)

Use this if you're already inside the ``gmail-mcp directory or the script path resolves cleanly:

npx @modelcontextprotocol/inspector uv run /Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/gmail-mcp/src/gmail/server.py \
  --creds-file-path ~/.gmail-mcp/credentials.json \
  --token-path ~/.gmail-mcp/token.json

2️⃣ Run with full project context (recommended)

This variant is more robust and works regardless of your working directory, because it explicitly tells uv which project directory to use and where your binaries are.

npx @modelcontextprotocol/inspector \
  /Users/sebastianwefers/.local/bin/uv \
  --directory /Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/gmail-mcp \
  run gmail \
  --creds-file-path ~/.gmail-mcp/credentials.json \
  --token-path ~/.gmail-mcp/token.json

🔍 What Happens

When you run either command, you should see output similar to:

Starting MCP inspector...
⚙️ Proxy server listening on localhost:6277
🔑 Session token: 8498939effc01e03c1b879efa72768e45608056ef1ad45e5c80344a7d9362a72
   Use this token to authenticate requests or set DANGEROUSLY_OMIT_AUTH=true to disable auth

🚀 MCP Inspector is up and running at:
   http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=8498939effc01e03c1b879efa72768e45608056ef1ad45e5c80344a7d9362a72

🌐 Opening browser...

This automatically opens a local browser window to the MCP Inspector UI, connected to your Gmail MCP server.

✅ Expected behavior:

• On first run, a browser window will prompt you to log in and approve access.
• After successful OAuth, a token file will be created:

~/.gmail-mcp/token.json

• Subsequent runs reuse this token — no re-auth required.
• You can now explore, invoke, and inspect your Gmail MCP tools visually (e.g., listEmails, sendEmail, modifyLabel, etc.) right from the web UI.

💻 Connecting the Gmail MCP Server to Claude Desktop

1. Open your Claude Desktop configuration file:

nano ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add this block (update paths if necessary):

{
  "mcpServers": {
    "gmail": {
      "command": "uv",
      "args": [
        "--directory",
        "/Users/sebastianwefers/Desktop/development/recruitment-agent-mcp-hackathon-winter25/src/mcp_servers/gmail-mcp",
        "run",
        "gmail",
        "--creds-file-path",
        "/Users/sebastianwefers/.gmail-mcp/credentials.json",
        "--token-path",
        "/Users/sebastianwefers/.gmail-mcp/token.json"
      ]
    }
  }
}

3. Save the file and restart Claude Desktop.

4. Open Settings → Model Context Protocol → Add Server, then connect to gmail.

Claude will now be able to:

• 📥 Read emails
• ✉️ Compose drafts
• 🏷 Send and modify Gmail messages directly from your account.

— all directly via your Gmail MCP server.

🧩 Why Deleting token.json Fixes the “invalid_grant” Error

The error occurs because the stored refresh token in token.json is expired or revoked, so Google rejects all refresh attempts. Deleting the file forces the app to start a new OAuth flow, prompting you to log in again and generating a new, valid refresh token — which restores access to the Gmail API.

# 1. Remove the invalid cached token
rm /Users/sebastianwefers/Desktop/projects/recruitment-agent-mcp-hackathon-winter25/secrets/gmail-mcp/token.json


# 2. Re-run the Gmail MCP server (which triggers OAuth again)
python -m src.mcp_servers.gmail_mcp

Then, when the script printed a Google sign-in URL, you:

1. Opened it in your browser,
2. Logged in to your Google account,
3. Approved the Gmail API access,
4. And the new valid token.json was automatically recreated at:

~/.gmail-mcp/token.json