Gmail MCP server

This Gmail server implements the Model Context Protocol (MCP) to allow AI assistants to manage your emails through a secure interface. It provides functionality for sending, reading, trashing emails and more, with user permission required for any actions.

Installation

Gmail API Setup

To use this MCP server, you'll need to set up credentials for the Gmail API:

1. Create a new Google Cloud project at console.cloud.google.com/projectcreate
2. Enable the Gmail API at console.cloud.google.com/workspace-api/products
3. Configure an OAuth consent screen at console.cloud.google.com/apis/credentials/consent
   • Select "external" (the app won't be published)
   • Add your personal email address as a "Test user"
4. Add the OAuth scope: https://www.googleapis.com/auth/gmail.modify
5. Create an OAuth Client ID at console.cloud.google.com/apis/credentials/oauthclient
   • Select application type "Desktop App"
6. Download the JSON file containing your OAuth keys
7. Save this file to a secure location on your computer

Usage

Starting the Server

When you start the server, you'll need to provide two important file paths:

• --creds-file-path: The absolute path to your OAuth credentials JSON file
• --token-path: The absolute path where authentication tokens will be stored

For example, you might store these in your home directory:

uv run gmail --creds-file-path "/home/user/.google/client_creds.json" --token-path "/home/user/.google/app_tokens.json"

Authentication

The first time you run the server, a browser window will open for authentication with your Google account. After authenticating, the tokens will be saved to the location specified in --token-path for future use.

Integrating with Claude Desktop

To use this server with Claude Desktop:

1. Edit your Claude Desktop configuration file (typically at ~/Library/Application Support/Claude/claude_desktop_config.json)
2. Add the following configuration:

{
  "mcpServers": {
    "gdrive": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/gmail/repo",
        "run",
        "gmail",
        "--creds-file-path",
        "/path/to/credentials.json",
        "--token-path",
        "/path/to/tokens.json"
      ]
    }
  }
}

Make sure to replace the placeholder paths with the actual paths on your system.

Available Functions

Managing Emails

The server provides these email management functions:

• Get Unread Emails: Retrieves a list of all unread emails
• Read Email: Gets the content of a specific email by ID
• Open Email: Opens a specific email in your browser
• Mark Email as Read: Marks a specific email as read
• Trash Email: Moves a specific email to the trash

Sending Emails

To send a new email, you'll need to provide:

• Recipient email address
• Subject line
• Message content

The AI assistant using this MCP server will always ask for permission before taking any action with your emails.

Troubleshooting

If you need to test the server independently of Claude, you can use the MCP Inspector tool:

npx @modelcontextprotocol/inspector uv run /path/to/repo/src/gmail/server.py --creds-file-path /path/to/credentials.json --token-path /path/to/tokens.json

This allows you to verify the server is working correctly before integrating it with an MCP client.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.