Gmail MCP Server

Gmail MCP Server

A Model Context Protocol (MCP) server that provides read-only Gmail access to Claude CLI with label-based filtering and container deployment support.

Why Use This?

• Security first: Read-only access means Claude cannot send, delete, or modify your emails. Label filtering lets you restrict which emails are visible.
• Summarize important information: Let Claude read and summarize emails so you can quickly understand what matters.
• Never miss important emails: Avoid overlooks by having Claude search and highlight critical information buried in your inbox.
• Save time: Quickly find and understand email content without manual searching through hundreds of messages.

Quick start:

1. Configure Claude CLI to trust your certificate (if self-signed):

   export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem
   

2. Add the server:

   claude mcp add --transport http gmail https://localhost:3000/mcp?allowed_labels=INBOX
   

Then ask Claude: "Summarize my unread emails from today" or "Find all emails about the project deadline"

Pro tip: Create a custom slash command for frequent tasks. Add to .claude/commands/email-summary.md:

Summarize unread emails from last 24 hours. Group by sender and highlight action items.

Then use /email-summary anytime.

Claude CLI Integration

Certificate Configuration

For self-signed or internal CA certificates, configure Claude CLI to trust them:

export NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

Alternatively, add to ~/.claude/settings.json:

{
  "env": {
    "NODE_EXTRA_CA_CERTS": "/path/to/ca-cert.pem"
  }
}

Note: The settings.json env configuration may not be applied due to a potential Claude CLI bug. If you experience certificate errors, use the shell environment variable approach instead.

Add Server via Command Line

claude mcp add --transport http gmail https://localhost:3001/mcp?allowed_labels=INBOX,STARRED

Label filtering via URL: Configure which Gmail labels Claude can access using the allowed_labels query parameter. Use comma-separated label names (e.g., INBOX,STARRED,IMPORTANT). This parameter is required.

Manual Configuration

Claude CLI configuration is stored at ~/.claude.json:

{
  "mcpServers": {
    "gmail": {
      "transport": "http",
      "url": "https://localhost:3001/mcp?allowed_labels=INBOX,STARRED"
    }
  }
}

Integration Steps

1. Ensure the service is running:

   curl http://localhost:3001/health
   

   Expected response: {"status":"ok"}

2. Add the server (see above)

3. Authenticate:

   • Start Claude Code: claude
   • Run /mcp command
   • Select the gmail server
   • Choose "Authenticate"
   • Complete Google OAuth in browser

4. Verify tools are available: Ask Claude: "What Gmail tools do you have?"

   Claude should list three Gmail tools:

   • list_messages
   • read_message
   • search_messages

Available Tools

1. list_messages

Lists Gmail messages filtered by allowed labels.

Parameters:

• maxResults (number, optional): Maximum number of messages to return (default: 10)
• pageToken (string, optional): Page token for pagination

Returns:

• Array of message summaries containing:
  • id: Message ID
  • threadId: Thread ID
  • snippet: Message preview
  • labelIds: Array of label IDs
  • from: Sender email address
  • subject: Email subject
  • date: Send date

2. read_message

Reads the full content of a specific message.

Parameters:

• messageId (string, required): The ID of the message to read
• maxSize (number, optional): Maximum body size in characters. If exceeded, body is truncated.

Returns:

• Full message object containing:
  • id: Message ID
  • threadId: Thread ID
  • labelIds: Array of label IDs
  • from: Sender email address
  • to: Recipient email address
  • subject: Email subject
  • date: Send date
  • body: Full email body (Markdown format)
  • bodySize: Original body size in characters
  • truncated: Whether body was truncated
  • snippet: Message preview

Note: This tool validates that the message has at least one allowed label before returning content. HTML-only emails are automatically converted to Markdown for better readability and token efficiency.

3. search_messages

Searches messages using Gmail query syntax.

Parameters:

• query (string, required): Gmail search query (e.g., "from:example@gmail.com subject:invoice")
• maxResults (number, optional): Maximum number of messages to return (default: 10)
• pageToken (string, optional): Page token for pagination

*Returns: