gmail

This MCP server provides access to Gmail data through a set of MCP tools that let an AI agent search threads, read email content, extract attachments, and draft emails in your own writing style. The server uses Gmail API scopes for readonly access, and compose access for creating or updating drafts. Core tools include: search_threads to query Gmail with advanced search operators, create_draft to produce or update drafts (with thread-aware context), extract_attachment_by_filename to pull text from attachments like PDFs or Word docs, and get_personal_email_style_guide to generate a style guide based on your recent writing. To use the persistent HTTP mode, run the server as a background HTTP daemon once (OAuth flow runs only once), then point MCP clients to the HTTP endpoint for all subsequent requests. When using the HTTP mode, you can connect multiple Cursor or Claude instances to the same running server without triggering repeated OAuth prompts.

Prerequisites:

• Go language installed (go build available)
• Google Cloud project with Gmail API enabled and OAuth2 credentials (Client ID and Client Secret)
• OpenAI API key for agent capabilities

Step-by-step installation:

1. Set up Google Cloud project and OAuth credentials as described in the README (create OAuth Client ID for a Desktop application and collect the Client ID and Client Secret).

2. Build the MCP server binary:

# from the project root
go build -o gmail-mcp-server

3. Run the server in persistent HTTP mode (recommended to avoid repeated OAuth popups):

# Start once; this will open a browser for OAuth the first time
./gmail-mcp-server --http 3000

Notes:

• The server authenticates on first run and then serves requests via HTTP at the configured port (e.g., http://localhost:3000).
• The default in-documentation port is 8080 for status pages if you don’t override the port; when using --http <port>, use the specified port.

4. Configure your MCP client to connect to the running server:

{
  "mcpServers": {
    "gmail": {
      "command": "C:/path/to/your/gmail-mcp-server",
      "env": {
        "GMAIL_CLIENT_ID": "your_client_id_here.apps.googleusercontent.com",
        "GMAIL_CLIENT_SECRET": "your_client_secret_here",
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

Optional: If you do not use HTTP mode, you can run the binary in stdio mode by launching the executable directly and letting your MCP client start it as a process (not recommended for OAuth popups).

Tips and notes:

• Use the persistent HTTP mode to avoid OAuth popups on every new tab or window. The server authenticates once and stays running.
• Ensure your OAuthClientId and OAuthClientSecret are kept secure and not checked into version control.
• The server exposes endpoints for status at http://localhost:8080 and health at http://localhost:8080/health when using HTTP persistence; verify the port you started on.
• Available MCP tools include: search_threads, create_draft, extract_attachment_by_filename, and get_personal_email_style_guide. Use get_personal_email_style_guide to tailor generated emails to your style.
• File storage (token.json and style guides) is kept in your app data directory per OS; you can force re-auth by deleting token.json if you need to re-consent or update scopes.
• This server supports reading and drafting but does not actually send emails (even though Gmail API permission includes send capability, the server intentionally doesn’t implement sending).
• If you run into OAuth scope or token issues, restarting in HTTP mode and re-authenticating once often resolves the problem.