MCP 服务器

Gmail MCP Server

Provides access to Gmail functionalities including listing unread emails, searching via query syntax, and managing messages through archiving or marking as read. It enables MCP clients to securely interact with and organize email data using the Gmail API.

README

Gmail MCP Server

A Model Context Protocol (MCP) server that provides Gmail access for Claude Code and other MCP clients. Built with FastMCP.

Features

list_unread - List unread emails from inbox
search - Search emails using Gmail query syntax
archive - Archive emails (removes from inbox)
mark_as_read - Mark emails as read without archiving
get_labels - Get all Gmail labels

Installation

No local installation required! Run directly from GitHub using uvx:

uvx --from git+https://github.com/fred-drake/gmail-mcp gmail-mcp

Setup

1. Create Google Cloud OAuth Credentials

Go to Google Cloud Console
Create a new project or select an existing one:
- Click the project dropdown at the top of the page
- Click "New Project", give it a name, and create it
- Make sure your new project is selected
Enable the Gmail API:
- Navigate to "APIs & Services" > "Library"
- Search for "Gmail API" and click on it
- Click "Enable"
Configure the OAuth consent screen (required before creating credentials):
- Go to "APIs & Services" > "OAuth consent screen"
- Select "External" as the user type and click "Create"
- Fill in the required fields:
  - App name: Choose any name (e.g., "Gmail MCP")
  - User support email: Select your email
  - Developer contact email: Enter your email
- Click "Save and Continue"
- On the "Scopes" page, click "Save and Continue" (no changes needed)
- On the "Test users" page:
  - Click "Add Users"
  - Enter the Gmail address you want to access (this is critical!)
  - Click "Add" then "Save and Continue"
- Click "Back to Dashboard"
Create OAuth credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose "Desktop app" as the application type
- Give it a name (e.g., "Gmail MCP Desktop")
- Click "Create"
- Click "Download JSON" to save the credentials file
- Store this file securely - you'll need the path for configuration

2. Set Environment Variables

Set the path to your OAuth credentials file:

export GMAIL_MCP_CREDENTIALS_PATH="/path/to/your/credentials.json"

Optionally, customize the token cache location (default: ~/.config/gmail-mcp/token.json):

export GMAIL_MCP_TOKEN_PATH="/custom/path/token.json"

3. Run OAuth Setup

Run the interactive setup to authenticate:

uvx --from git+https://github.com/fred-drake/gmail-mcp gmail-mcp --setup

This will open a browser window for Google OAuth authentication. After authorizing, the token will be cached for future use.

MCP Client Configuration

Claude Code

Add to your Claude Code MCP settings:

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fred-drake/gmail-mcp", "gmail-mcp"],
      "env": {
        "GMAIL_MCP_CREDENTIALS_PATH": "/path/to/your/credentials.json"
      }
    }
  }
}

With Custom Token Path

{
  "mcpServers": {
    "gmail": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/fred-drake/gmail-mcp", "gmail-mcp"],
      "env": {
        "GMAIL_MCP_CREDENTIALS_PATH": "/path/to/your/credentials.json",
        "GMAIL_MCP_TOKEN_PATH": "/custom/path/token.json"
      }
    }
  }
}