Gmail MCP Server

MCP server for Gmail API with OAuth2 authentication. Provides programmatic access to Gmail for sending emails, managing labels, creating filters, and handling attachments through AI assistants.

💡 Built for Your IDE: This MCP server is designed to work seamlessly with Cursor Cloud Geminis and other IDE-integrated AI assistants. Experience native email management directly within your development environment—no need to switch between applications. You can also use it with desktop tools like Claude Desktop, but the native IDE integration provides the smoothest experience.

Requirements

• Node.js 18.0.0+
• Google Cloud Project with Gmail API enabled
• OAuth 2.0 credentials (Desktop application or Web application type)

Quick Start

The easiest way to get started is using the setup command:

git clone https://github.com/pouyanafisi/gmail-mcp.git
cd gmail-mcp
npm install
npm run build
npm run setup    # Automatically configures MCP for Cursor IDE
npm run auth     # Authenticate with Gmail

The npm run setup command automatically:

• ✅ Creates the MCP configuration file for Cursor IDE
• ✅ Provides instructions for Claude Desktop setup
• ✅ Verifies your build and credentials

After setup, restart your IDE and start managing Gmail directly from your AI assistant!

Installation

Install from npm (Recommended)

npm install -g @pouyanafisi/gmail-mcp

Or install locally:

npm install @pouyanafisi/gmail-mcp

Install from source

git clone https://github.com/pouyanafisi/gmail-mcp.git
cd gmail-mcp
npm install
npm run build
npm run setup    # Automatically configures MCP for your IDE

Google Cloud Setup

1. Enable Gmail API in Google Cloud Console
2. Create OAuth 2.0 credentials (Desktop application or Web application)
3. Download credentials JSON
4. Save as gcp-oauth.keys.json in project root or ~/.gmail-mcp/

Configuration

Using npm package

If installed globally:

{
  "mcpServers": {
    "gmail": {
      "command": "gmail-mcp"
    }
  }
}

If installed locally, use npx:

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

Using source installation

{
  "mcpServers": {
    "gmail": {
      "command": "node",
      "args": ["/absolute/path/to/gmail-mcp/dist/index.js"]
    }
  }
}