Gmail MCP server

The Gmail MCP Server provides a powerful interface to interact with Gmail APIs programmatically. It enables reading, sending, and managing emails across multiple Gmail accounts with features like attachment handling, advanced search, and real-time monitoring.

Prerequisites

Before running the Gmail MCP server, ensure you have:

• Python 3.12 or higher
• Google Cloud Project with Gmail API enabled
• OAuth 2.0 Client ID credentials
• Required Python packages

Installation Options

Installing via Smithery

npx -y @smithery/cli install @Quantum-369/Gmail-mcp-server --client claude

Manual Installation

1. Clone the repository:

git clone <your-repository-url>
cd gmail-mcp-server

2. Create and activate a virtual environment:

python -m venv venv
# On Windows
venv\Scripts\activate
# On Unix/MacOS
source venv/bin/activate

3. Install dependencies:

pip install .

Running on Ubuntu

1. Install Python 3.12 and create a virtual environment:

sudo apt install python3.12 python3.12-venv -y
python3.12 -m venv venv
source venv/bin/activate

2. Place your downloaded client_secret.json in the project root.

3. Generate an OAuth token:

python gmail_token_creator.py

4. Start the server:

python gmail_server.py

Google Cloud Project Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Gmail API for your project
4. Create OAuth 2.0 credentials:
   • Go to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Choose "Desktop app" as application type
   • Download the client configuration file
5. Rename the downloaded file to client_secret.json and place it in the project root directory

Configuration

1. Set up email identifiers in gmail_token_creator.py:

email_identifier = '[email protected]'  # Change this for each account

2. Run the token creator to authenticate your Gmail accounts:

python gmail_token_creator.py

3. Follow the authorization URL in your browser, complete the Google consent flow, and enter the verification code if prompted.

4. Repeat for each Gmail account you want to integrate.

Running the Server

Standard Method

python gmail_server.py

Using Docker

docker build -t gmail-mcp-server .
docker run -v $(pwd)/client_secret.json:/app/client_secret.json \
           -v $(pwd)/token_files:/app/token_files gmail-mcp-server

Using the Gmail API Tools

Sending Emails

await send_gmail(
    email_identifier="[email protected]",
    to="[email protected]",
    subject="Test Subject",
    body="Email body content",
    attachment_paths=["path/to/attachment"]
)

Searching Emails

await search_email_tool(
    email_identifier="[email protected]",
    query="from:[email protected]",
    max_results=30,
    include_conversations=True
)

Reading Latest Emails

await read_latest_emails(
    email_identifier="[email protected]",
    max_results=5,
    download_attachments=False
)

Downloading Attachments

await download_email_attachments(
    email_identifier="[email protected]",
    msg_id="message_id",
    download_all_in_thread=False
)

Security Best Practices

• Store client_secret.json securely and never commit to version control
• Keep token files secure and add them to .gitignore
• Use environment variables for sensitive information
• Regularly rotate OAuth credentials
• Monitor API usage and set appropriate quotas

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "gmail-mcp-server" '{"command":"npx","args":["-y","@smithery/cli","install","@Quantum-369/Gmail-mcp-server","--client","claude"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "gmail-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@smithery/cli",
                "install",
                "@Quantum-369/Gmail-mcp-server",
                "--client",
                "claude"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "gmail-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@smithery/cli",
                "install",
                "@Quantum-369/Gmail-mcp-server",
                "--client",
                "claude"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect