Gmail MCP Server

A Model Context Protocol server that lets an AI assistant (Claude Desktop, Claude API, etc.) read unread Gmail messages and create threaded draft replies — without ever sending email automatically.

What this server does

The server communicates with Claude Desktop over stdio using the MCP JSON-RPC protocol. It never sends email — only creates drafts.

Related MCP server: Gmail MCP Server

Prerequisites

• Python 3.10+

• A Google account

• Claude Desktop installed

Quick start

1. Clone and install

git clone <this-repo>
cd gmail-mcp-server
bash scripts/setup.sh
source .venv/bin/activate

2. Set up Gmail API credentials

Follow the detailed guide in docs/gmail_api_setup.md.

Summary:

1. Create a Google Cloud project.

2. Enable the Gmail API.

3. Configure the OAuth consent screen (External, test mode is fine).

4. Add scopes: gmail.readonly + gmail.compose.

5. Create an OAuth 2.0 Desktop App credential.

6. Download credentials.json → place in project root.

3. Authenticate

python scripts/auth_check.py

A browser window opens. Sign in and approve access. token.pickle is saved.

4. Test the server manually

# Start the server (press Ctrl-C to stop)
gmail-mcp

The server waits for JSON-RPC on stdin. You can send a test message:

echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | gmail-mcp

5. Configure Claude Desktop

Edit claude_desktop_config.json (see docs/claude_desktop_config.md):

{
  "mcpServers": {
    "gmail": {
      "command": "/absolute/path/to/.venv/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "cwd": "/absolute/path/to/gmail-mcp-server",
      "env": {
        "GMAIL_CREDENTIALS_PATH": "/absolute/path/to/credentials.json",
        "GMAIL_TOKEN_PATH": "/absolute/path/to/token.pickle"
      }
    }
  }
}

Restart Claude Desktop. The gmail tools will appear automatically.

Example Claude prompts

Check my unread emails and tell me which ones need urgent attention.

I have an unread email about a refund request. Draft a polite reply
using our style guide, then save it as a draft.

Fetch my 5 newest unread emails. For each one, tell me the sender,
subject, and a one-sentence summary.

Use get_reply_context to see our templates, then create a draft reply
to the meeting invite email.

Project structure

gmail-mcp-server/
├── src/
│   └── gmail_mcp_server/
│       ├── __init__.py
│       ├── server.py          # MCP server entry point & tool definitions
│       ├── auth.py            # OAuth 2.0 credential management
│       ├── gmail_tools.py     # Gmail API logic (read emails, create drafts)
│       └── context.py         # Stretch-goal: style guide, templates, KB search
├── context/
│   ├── style_guide.md         # Writing style guide (edit to match your voice)
│   ├── templates.json         # Reply templates
│   └── knowledge_base/        # .md/.txt files Claude can search
├── scripts/
│   ├── setup.sh               # One-time environment setup
│   └── auth_check.py          # OAuth flow + credential verification
├── docs/
│   ├── mcp_concepts.md        # How MCP tools work (detailed explanation)
│   ├── gmail_api_setup.md     # Step-by-step Google Cloud setup
│   └── claude_desktop_config.md  # Claude Desktop config + example prompts
├── pyproject.toml
├── .env.example
└── .gitignore

How MCP tools work (summary)

MCP tools are callable functions that an LLM can invoke via JSON-RPC:

1. Discovery — Claude calls tools/list; the server returns tool names, descriptions, and JSON Schemas for their arguments.

2. Decision — The LLM decides which tool to call based on the description and the user's request.

3. Invocation — Claude calls tools/call with the tool name and arguments.

4. Result — The server returns a TextContent block (JSON string) that Claude reads and incorporates into its response.

See docs/mcp_concepts.md for a full explanation with sequence diagrams and annotated code.

Stretch goal: external context

The get_reply_context tool pulls in:

• Style guide (context/style_guide.md) – tone, structure, phrases to use/avoid.

• Templates (context/templates.json) – starting points for common reply types.

• Knowledge base (context/knowledge_base/) – searched by keyword.

To connect real cloud sources:

• Google Docs – enable the Docs API, add documents.readonly scope, fetch document content via docs.documents().get().

• Notion – install notion-client, query a database with your integration token.

• Vector search – replace search_knowledge_base() in context.py with chromadb or hnswlib for semantic search over larger document sets.

Security notes

• credentials.json and token.pickle are in .gitignore — never commit them.

• The server only requests gmail.readonly and gmail.compose scopes.

• No email is ever sent automatically; create_draft_reply only calls drafts.create, not messages.send.

• The OAuth consent screen is in "Testing" mode by default — only you can authenticate.

Troubleshooting

For more, see docs/gmail_api_setup.md.

License

MIT