Gmail MCP Local Server

A local MCP (Model Context Protocol) server that gives Claude the ability to send emails, manage drafts, and search Gmail — capabilities missing from Anthropic's built-in Gmail connector.

What is MCP and how does this work?

MCP is a protocol that lets Claude call real-world tools. When you register an MCP server, Claude Desktop launches it as a background subprocess and routes tool calls to it over stdin/stdout.

You talk to Claude
       │
       ▼
Claude decides which tool to use
       │
       ▼
MCP server executes the action
(send email, search messages, etc.)
       │
       ▼
Real world effect happens

You never run this script manually. Claude Desktop starts and stops it automatically.

Related MCP server: gmail-mcp-server

Tools

Setup

1. Install dependencies

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Google Cloud setup

You need a credentials.json from Google Cloud Console. This is your app's identity card with Google.

1. Go to console.cloud.google.com

2. Create a project

3. Go to APIs & Services → Library → enable Gmail API

4. Go to APIs & Services → OAuth consent screen

   • Choose External → fill in app name and your email

   • Under Test users, add your Gmail address

5. Go to APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID

   • Application type: Desktop app

   • Download the JSON and save it as credentials.json in this folder

Copy .env.example to .env and fill in your values (these match what's inside credentials.json):

cp .env.example .env

3. Register with Claude Desktop

Open ~/Library/Application Support/Claude/claude_desktop_config.json and add:

{
  "mcpServers": {
    "gmail": {
      "command": "/FULL/PATH/TO/gmail_mcp/venv/bin/python3",
      "args": ["/FULL/PATH/TO/gmail_mcp/gmail_mcp.py"]
    }
  }
}

Restart Claude Desktop.

First-run OAuth (one time only)

The first time Claude uses a Gmail tool, a browser window will open asking you to sign in with Google and grant access. After you approve:

• A token.json file is saved in this folder

• All future runs reuse this token silently

• The token auto-refreshes when it expires — no action needed

Why the test user step matters: Google blocks OAuth for apps in "Testing" mode unless your email is explicitly listed as a test user. That's the 403: access_denied error if skipped.

How Claude Desktop manages the server

Claude Desktop starts
       │
       │  spawns subprocess automatically
       ▼
gmail_mcp.py runs in background
       │
       │  reads token.json for auth
       ▼
Gmail API (Google's servers)

• No manual start needed — Claude Desktop handles it

• The server only runs while Claude Desktop is open

• If you use a scheduler, it only fires while Claude Desktop is running on your machine

Security

• token.json contains a live OAuth refresh token — full Gmail access. Keep it private.

• credentials.json contains your app's client secret. Keep it private.

• Neither file is committed to git (covered by .gitignore)

• If your token is compromised, revoke it at myaccount.google.com/permissions and delete token.json to force re-auth

What else can you build with MCP?

MCP works with any API. Some ideas:

• Google Calendar — create and read events

• Notion — read/write pages and databases

• Slack — send messages, read channels

• GitHub — open issues, create PRs

• Google Sheets — read/write spreadsheet data

• SMS / WhatsApp — send messages via Twilio

• Local filesystem — read/write files in specific folders

• Databases — query SQLite or Postgres

The pattern is always the same: write a Python file with @mcp.tool() functions, register it in claude_desktop_config.json, and Claude can act in the real world through it.