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.

---

Tools

Tool	Description
gmail_send_email	Compose and immediately send an email
gmail_send_draft	Send an existing draft by its draft ID
gmail_create_draft	Save a composed email as a draft without sending
gmail_list_drafts	List saved drafts with subject and recipient info
gmail_search_messages	Search messages using Gmail query syntax
gmail_read_message	Read the full decoded body of a message

---

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.