Gmail MCP server

The Gmail MCP Server provides a powerful interface to interact with Gmail APIs programmatically. It allows you to read, send, and manage emails across multiple Gmail accounts through a server built on the Model Context Protocol (MCP) framework.

Prerequisites

Before running the Gmail MCP server, ensure you have:

1. Python 3.12 or higher
2. Google Cloud Project with Gmail API enabled
3. OAuth 2.0 Client ID credentials
4. Required Python packages

Installation

Via Smithery

Install automatically via Smithery for Claude Desktop:

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 .

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:
   • Navigate to "APIs & Services" > "Credentials"
   • Click "Create Credentials" > "OAuth client ID"
   • Select "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. Repeat the process for each Gmail account you want to integrate

Usage

Starting the Server

To start the MCP server:

python gmail_server.py

Working with Emails

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 it 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

Troubleshooting

The server logs information to gmail_mcp.log. If you encounter issues:

• Check the log file for detailed error messages
• Ensure your OAuth credentials are valid
• Verify you have the correct permissions for the Gmail account
• Confirm the Gmail API is enabled in your Google Cloud Project

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