Gmail

by ajbr0wn

7 stars

Not rated

GitHub

About

Integrates Gmail functionality to enable secure access, search, and analysis of email contents using OAuth2 authentication and the Gmail API.

Details

Author: ajbr0wn
Repository: ajbr0wn/gmail-mcp-server
GitHub stars: 7
Categories: Communication, Other, Automation, Productivity, Developer Tools, Design, AI, Search, Infrastructure, API, Frontend

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name Gmail

Command (node, npx, python, etc.) /path/to/conda/envs/mcp-gmail/bin/python
Arguments
- Argument 1 -m
- Argument 2 gmail_mcp_server.server
Environment
- PYTHONPATH /path/to/gmail-mcp-server/src
- GMAIL_TOKEN_FILE /path/to/token.json
- GMAIL_CREDENTIALS_FILE /path/to/credentials.json
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/python.exe"
        }
    }
}

JSON

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

From the repository

1. Create a Google Cloud Project at https://console.cloud.google.com/
2. Enable the Gmail API
3. Create OAuth 2.0 credentials:
- Application type: Desktop application
- Download the credentials as credentials.json

conda create -n mcp-gmail python=3.12 conda activate mcp-gmail

cd gmail-mcp-server pip install -e .

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "/path/to/conda/envs/mcp-gmail/bin/python",
      "args": ["-m", "gmail_mcp_server.server"],
      "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json",
        "GMAIL_TOKEN_FILE": "/path/to/token.json"
      }
    }
  }
}

Replace /path/to/ with your actual paths. The token file will be created automatically when you first authenticate.

- GMAIL_CREDENTIALS_FILE (required): Path to your Google OAuth credentials file
- GMAIL_TOKEN_FILE (required): Path where the authentication token will be saved

For testing, you can run the server directly:

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \

GMAIL_TOKEN_FILE="/path/to/token.json" \

python -m gmail_mcp_server.server

`search_emails`

Search Gmail emails with a query. Parameters: query (required) - Gmail search query (uses Gmail's standard search syntax), max_results (optional) - Maximum number of results to return (default: 10)

- search_emails
- Description: Search Gmail emails with a query
- Parameters:
- query (required): Gmail search query (uses Gmail's standard search syntax)
- max_results (optional): Maximum number of results to return (default: 10)

Example search:

Could you show me any emails from sanrio in the last two days?

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "gmail": {
            "env": {
                "PYTHONPATH": "/path/to/gmail-mcp-server/src",
                "GMAIL_TOKEN_FILE": "/path/to/token.json",
                "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
            },
            "args": [
                "-m",
                "gmail_mcp_server.server"
            ],
            "command": "/path/to/conda/envs/mcp-gmail/bin/python"
        }
    }
}

Linux

{
    "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_TOKEN_FILE": "/path/to/token.json",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
    },
    "args": [
        "-m",
        "gmail_mcp_server.server"
    ],
    "command": "/path/to/conda/envs/mcp-gmail/bin/python"
}

Macos

{
    "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_TOKEN_FILE": "/path/to/token.json",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
    },
    "args": [
        "-m",
        "gmail_mcp_server.server"
    ],
    "command": "/path/to/conda/envs/mcp-gmail/bin/python"
}

Windows

{
    "env": {
        "PYTHONPATH": "/path/to/gmail-mcp-server/src",
        "GMAIL_TOKEN_FILE": "/path/to/token.json",
        "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json"
    },
    "args": [
        "-m",
        "gmail_mcp_server.server"
    ],
    "command": "/path/to/conda/envs/mcp-gmail/python.exe"
}

An MCP server for integrating with the Gmail API to manage emails.

An MCP (Model Context Protocol) server that provides Gmail integration capabilities to MCP clients like Claude Desktop.

- View recent emails from your Gmail inbox
- Search emails using Gmail's search syntax
- Secure OAuth2 authentication with Gmail API
- Create a Google Cloud Project athttps://console.cloud.google.com/
- Enable the Gmail API
- Create OAuth 2.0 credentials:

- Application type: Desktop application
- Download the credentials ascredentials.json

# Create a conda environment conda create -n mcp-gmail python=3.12 conda activate mcp-gmail # Install the package cd gmail-mcp-server pip install -e .

Add to yourclaude_desktop_config.json:

{ "mcpServers": { "gmail": { "command": "/path/to/conda/envs/mcp-gmail/bin/python", "args": ["-m", "gmail_mcp_server.server"], "env": { "PYTHONPATH": "/path/to/gmail-mcp-server/src", "GMAIL_CREDENTIALS_FILE": "/path/to/credentials.json", "GMAIL_TOKEN_FILE": "/path/to/token.json" } } } }

Replace/path/to/with your actual paths. The token file will be created automatically when you first authenticate.

When you first try to access Gmail through Claude, you'll be prompted to authorize the application in your browser. After authorization, your credentials will be saved to the token file for future use.

- gmail://inbox/recent- Returns your 10 most recent emails

- search_emails

- Description: Search Gmail emails with a query
- Parameters:

- query(required): Gmail search query (uses Gmail's standard search syntax)
- max_results(optional): Maximum number of results to return (default: 10)

Could you show me any emails from sanrio in the last two days?

This server requires OAuth2 authentication with Gmail:

- You'll be prompted to authorize access in your browser on first use
- Credentials are stored locally in the specified token file
- Access can be revoked at any time through your Google Account settings
- Only read access to Gmail is requested (no write permissions)

- GMAIL_CREDENTIALS_FILE(required): Path to your Google OAuth credentials file
- GMAIL_TOKEN_FILE(required): Path where the authentication token will be saved

For testing, you can run the server directly:

GMAIL_CREDENTIALS_FILE="/path/to/credentials.json" \ GMAIL_TOKEN_FILE="/path/to/token.json" \ python -m gmail_mcp_server.server

The server uses the Model Context Protocol to provide:

- Resource access to recent emails
- Tool support for email search
- Secure OAuth2 authentication flow
- Automatic token refresh

The server logs detailed information about its operations to stderr, including:

- Server startup information
- Authentication status
- Resource and tool usage
- Any errors or issues

Pull requests are welcome! Please ensure to:

- Update documentation for any new features
- Add appropriate error handling
- Test OAuth flow with new features
- Follow existing code style

Query live Gmail data using LLMs via CData's read-only MCP server.

Search and delete emails in your Gmail account.

Enables AI assistants to manage Gmail through natural language interactions.

A standardized interface for managing, sending, and retrieving emails through the Gmail API.

Manage your Gmail account, including sending, reading, and organizing emails.

A super simple and tiny MCP server for gmail in python

Allows AI agents to search Gmail threads, learn your writing style, and draft emails.

An MCP server that enables AI models to interact directly with the Gmail API to manage emails.

Most email MCP servers only read from IMAP. mail-mcp does everything: 30 tools for reading, searching, sending, replying, forwarding, and bulk operations across IMAP, SMTP, Microsoft Graph API, and Exchange Web Services. Multi-account, native OAuth2, built in Rust. Works with Gmail, Microsoft 365, Hotmail/Outlook.com, Zoho, and any standard IMAP/SMTP server.

MCP server for structured, read-only email access. Exposes a minimal, auditable API surface — AI agents can search and read emails, but cannot send, delete, or modify your mailbox.

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

search_emails

Claude Desktop / Cursor

Linux

Macos

Windows

Install

More like this

@mendableai/firecrawl Mcp Server

Umut Naci

Playwright

Sequential Thinking

Slack

Filesystem

`search_emails`