Gmail-MCP-Server

A Model Context Protocol (MCP) server for Gmail integration in Claude Desktop with auto authentication support. This server enables AI assistants to manage Gmail through natural language interactions.

Stars: 126

Visit

Gmail AutoAuth MCP Server is a Model Context Protocol (MCP) server designed for Gmail integration in Claude Desktop. It supports auto authentication and enables AI assistants to manage Gmail through natural language interactions. The server provides comprehensive features for sending emails, reading messages, managing labels, searching emails, and batch operations. It offers full support for international characters, email attachments, and Gmail API integration. Users can install and authenticate the server via Smithery or manually with Google Cloud Project credentials. The server supports both Desktop and Web application credentials, with global credential storage for convenience. It also includes Docker support and instructions for cloud server authentication.

README:

Gmail AutoAuth MCP Server

Features

Send emails with subject, content, attachments, and recipients
Full support for international characters in subject lines and email content
Read email messages by ID with advanced MIME structure handling
View email attachments information (filenames, types, sizes)
Search emails with various criteria (subject, sender, date range)
Comprehensive label management with ability to create, update, delete and list labels
List all available Gmail labels (system and user-defined)
List emails in inbox, sent, or custom labels
Mark emails as read/unread
Move emails to different labels/folders
Delete emails
Batch operations for efficiently processing multiple emails at once
Full integration with Gmail API
Simple OAuth2 authentication flow with auto browser launch
Support for both Desktop and Web application credentials
Global credential storage for convenience

Installation & Authentication

Installing via Smithery

To install Gmail AutoAuth for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @gongrzhe/server-gmail-autoauth-mcp --client claude

Installing Manually

Create a Google Cloud Project and obtain credentials:

a. Create a Google Cloud Project:
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API for your project
b. Create OAuth 2.0 Credentials:
- Go to "APIs & Services" > "Credentials"
- Click "Create Credentials" > "OAuth client ID"
- Choose either "Desktop app" or "Web application" as application type
- Give it a name and click "Create"
- For Web application, add http://localhost:3000/oauth2callback to the authorized redirect URIs
- Download the JSON file of your client's OAuth keys
- Rename the key file to gcp-oauth.keys.json
Run Authentication:

You can authenticate in two ways:

a. Global Authentication (Recommended):
```
# First time: Place gcp-oauth.keys.json in your home directory's .gmail-mcp folder
mkdir -p ~/.gmail-mcp
mv gcp-oauth.keys.json ~/.gmail-mcp/

# Run authentication from anywhere
npx @gongrzhe/server-gmail-autoauth-mcp auth
```
b. Local Authentication:
```
# Place gcp-oauth.keys.json in your current directory
# The file will be automatically copied to global config
npx @gongrzhe/server-gmail-autoauth-mcp auth
```
The authentication process will:
- Look for gcp-oauth.keys.json in the current directory or ~/.gmail-mcp/
- If found in current directory, copy it to ~/.gmail-mcp/
- Open your default browser for Google authentication
- Save credentials as ~/.gmail-mcp/credentials.json
Note:
- After successful authentication, credentials are stored globally in ~/.gmail-mcp/ and can be used from any directory
- Both Desktop app and Web application credentials are supported
- For Web application credentials, make sure to add http://localhost:3000/oauth2callback to your authorized redirect URIs
Configure in Claude Desktop:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-gmail-autoauth-mcp"
      ]
    }
  }
}

Docker Support

If you prefer using Docker:

Authentication:

docker run -i --rm \
  --mount type=bind,source=/path/to/gcp-oauth.keys.json,target=/gcp-oauth.keys.json \
  -v mcp-gmail:/gmail-server \
  -e GMAIL_OAUTH_PATH=/gcp-oauth.keys.json \
  -e "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json" \
  -p 3000:3000 \
  mcp/gmail auth

Usage:

{
  "mcpServers": {
    "gmail": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-v",
        "mcp-gmail:/gmail-server",
        "-e",
        "GMAIL_CREDENTIALS_PATH=/gmail-server/credentials.json",
        "mcp/gmail"
      ]
    }
  }
}

Cloud Server Authentication

For cloud server environments (like n8n), you can specify a custom callback URL during authentication:

npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

Setup Instructions for Cloud Environment

Configure Reverse Proxy:
- Set up your n8n container to expose a port for authentication
- Configure a reverse proxy to forward traffic from your domain (e.g., gmail.gongrzhe.com) to this port
DNS Configuration:
- Add an A record in your DNS settings to resolve your domain to your cloud server's IP address
Google Cloud Platform Setup:
- In your Google Cloud Console, add your custom domain callback URL (e.g., https://gmail.gongrzhe.com/oauth2callback) to the authorized redirect URIs list

Run Authentication:

npx @gongrzhe/server-gmail-autoauth-mcp auth https://gmail.gongrzhe.com/oauth2callback

Configure in your application:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": [
        "@gongrzhe/server-gmail-autoauth-mcp"
      ]
    }
  }
}

This approach allows authentication flows to work properly in environments where localhost isn't accessible, such as containerized applications or cloud servers.

Available Tools

The server provides the following tools that can be used through Claude Desktop:

1. Send Email (`send_email`)

Sends a new email immediately.

{
  "to": ["[email protected]"],
  "subject": "Meeting Tomorrow",
  "body": "Hi,\n\nJust a reminder about our meeting tomorrow at 10 AM.\n\nBest regards",
  "cc": ["[email protected]"],
  "bcc": ["[email protected]"]
}

2. Draft Email (`draft_email`)

Creates a draft email without sending it.

{
  "to": ["[email protected]"],
  "subject": "Draft Report",
  "body": "Here's the draft report for your review.",
  "cc": ["[email protected]"]
}

3. Read Email (`read_email`)

Retrieves the content of a specific email by its ID.

{
  "messageId": "182ab45cd67ef"
}

4. Search Emails (`search_emails`)

Searches for emails using Gmail search syntax.

{
  "query": "from:[email protected] after:2024/01/01 has:attachment",
  "maxResults": 10
}

5. Modify Email (`modify_email`)

Adds or removes labels from emails (move to different folders, archive, etc.).

{
  "messageId": "182ab45cd67ef",
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"]
}

6. Delete Email (`delete_email`)

Permanently deletes an email.

{
  "messageId": "182ab45cd67ef"
}

7. List Email Labels (`list_email_labels`)

Retrieves all available Gmail labels.

{}

8. Create Label (`create_label`)

Creates a new Gmail label.

{
  "name": "Important Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

9. Update Label (`update_label`)

Updates an existing Gmail label.

{
  "id": "Label_1234567890",
  "name": "Urgent Projects",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

10. Delete Label (`delete_label`)

Deletes a Gmail label.

{
  "id": "Label_1234567890"
}

11. Get or Create Label (`get_or_create_label`)

Gets an existing label by name or creates it if it doesn't exist.

{
  "name": "Project XYZ",
  "messageListVisibility": "show",
  "labelListVisibility": "labelShow"
}

12. Batch Modify Emails (`batch_modify_emails`)

Modifies labels for multiple emails in efficient batches.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "addLabelIds": ["IMPORTANT"],
  "removeLabelIds": ["INBOX"],
  "batchSize": 50
}

13. Batch Delete Emails (`batch_delete_emails`)

Permanently deletes multiple emails in efficient batches.

{
  "messageIds": ["182ab45cd67ef", "182ab45cd67eg", "182ab45cd67eh"],
  "batchSize": 50
}

Advanced Search Syntax

The search_emails tool supports Gmail's powerful search operators:

Operator	Example	Description
`from:`	`from:[email protected]`	Emails from a specific sender
`to:`	`to:[email protected]`	Emails sent to a specific recipient
`subject:`	`subject:"meeting notes"`	Emails with specific text in the subject
`has:attachment`	`has:attachment`	Emails with attachments
`after:`	`after:2024/01/01`	Emails received after a date
`before:`	`before:2024/02/01`	Emails received before a date
`is:`	`is:unread`	Emails with a specific state
`label:`	`label:work`	Emails with a specific label

You can combine multiple operators: from:[email protected] after:2024/01/01 has:attachment

Advanced Features

Email Content Extraction

The server intelligently extracts email content from complex MIME structures:

Prioritizes plain text content when available
Falls back to HTML content if plain text is not available
Handles multi-part MIME messages with nested parts
Processes attachments information (filename, type, size)
Preserves original email headers (From, To, Subject, Date)

International Character Support

The server fully supports non-ASCII characters in email subjects and content, including:

Turkish, Chinese, Japanese, Korean, and other non-Latin alphabets
Special characters and symbols
Proper encoding ensures correct display in email clients

Comprehensive Label Management

The server provides a complete set of tools for managing Gmail labels:

Create Labels: Create new labels with customizable visibility settings
Update Labels: Rename labels or change their visibility settings
Delete Labels: Remove user-created labels (system labels are protected)
Find or Create: Get a label by name or automatically create it if not found
List All Labels: View all system and user labels with detailed information
Label Visibility Options: Control how labels appear in message and label lists

Label visibility settings include:

messageListVisibility: Controls whether the label appears in the message list (show or hide)
labelListVisibility: Controls how the label appears in the label list (labelShow, labelShowIfUnread, or labelHide)

These label management features enable sophisticated organization of emails directly through Claude, without needing to switch to the Gmail interface.

Batch Operations

The server includes efficient batch processing capabilities:

Process up to 50 emails at once (configurable batch size)
Automatic chunking of large email sets to avoid API limits
Detailed success/failure reporting for each operation
Graceful error handling with individual retries
Perfect for bulk inbox management and organization tasks

Security Notes

OAuth credentials are stored securely in your local environment (~/.gmail-mcp/)
The server uses offline access to maintain persistent authentication
Never share or commit your credentials to version control
Regularly review and revoke unused access in your Google Account settings
Credentials are stored globally but are only accessible by the current user

Troubleshooting

OAuth Keys Not Found
- Make sure gcp-oauth.keys.json is in either your current directory or ~/.gmail-mcp/
- Check file permissions
Invalid Credentials Format
- Ensure your OAuth keys file contains either web or installed credentials
- For web applications, verify the redirect URI is correctly configured
Port Already in Use
- If port 3000 is already in use, please free it up before running authentication
- You can find and stop the process using that port
Batch Operation Failures
- If batch operations fail, they automatically retry individual items
- Check the detailed error messages for specific failures
- Consider reducing the batch size if you encounter rate limiting

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT

Support

If you encounter any issues or have questions, please file an issue on the GitHub repository.

For Tasks:

Click tags to check more tools for each tasks

send email read email search emails modify email labels delete email

For Jobs:

ai assistant developer email marketing specialist software engineer data analyst virtual assistant

Alternative AI tools for Gmail-MCP-Server

Similar Open Source Tools

Gmail-MCP-Server

github

: 126

minions

Minions is a communication protocol that enables small on-device models to collaborate with frontier models in the cloud. By only reading long contexts locally, it reduces cloud costs with minimal or no quality degradation. The repository provides a demonstration of the protocol.

github

: 1.1k

scylla

Scylla is an intelligent proxy pool tool designed for humanities, enabling users to extract content from the internet and build their own Large Language Models in the AI era. It features automatic proxy IP crawling and validation, an easy-to-use JSON API, a simple web-based user interface, HTTP forward proxy server, Scrapy and requests integration, and headless browser crawling. Users can start using Scylla with just one command, making it a versatile tool for various web scraping and content extraction tasks.

github

: 3.9k

mcp

Semgrep MCP Server is a beta server under active development for using Semgrep to scan code for security vulnerabilities. It provides a Model Context Protocol (MCP) for various coding tools to get specialized help in tasks. Users can connect to Semgrep AppSec Platform, scan code for vulnerabilities, customize Semgrep rules, analyze and filter scan results, and compare results. The tool is published on PyPI as semgrep-mcp and can be installed using pip, pipx, uv, poetry, or other methods. It supports CLI and Docker environments for running the server. Integration with VS Code is also available for quick installation. The project welcomes contributions and is inspired by core technologies like Semgrep and MCP, as well as related community projects and tools.

github

: 58

aiavatarkit

AIAvatarKit is a tool for building AI-based conversational avatars quickly. It supports various platforms like VRChat and cluster, along with real-world devices. The tool is extensible, allowing unlimited capabilities based on user needs. It requires VOICEVOX API, Google or Azure Speech Services API keys, and Python 3.10. Users can start conversations out of the box and enjoy seamless interactions with the avatars.

github

: 413

langchainrb

Langchain.rb is a Ruby library that makes it easy to build LLM-powered applications. It provides a unified interface to a variety of LLMs, vector search databases, and other tools, making it easy to build and deploy RAG (Retrieval Augmented Generation) systems and assistants. Langchain.rb is open source and available under the MIT License.

github

: 1.7k

agentpress

AgentPress is a collection of simple but powerful utilities that serve as building blocks for creating AI agents. It includes core components for managing threads, registering tools, processing responses, state management, and utilizing LLMs. The tool provides a modular architecture for handling messages, LLM API calls, response processing, tool execution, and results management. Users can easily set up the environment, create custom tools with OpenAPI or XML schema, and manage conversation threads with real-time interaction. AgentPress aims to be agnostic, simple, and flexible, allowing users to customize and extend functionalities as needed.

github

: 67

json-repair

JSON Repair is a toolkit designed to address JSON anomalies that can arise from Large Language Models (LLMs). It offers a comprehensive solution for repairing JSON strings, ensuring accuracy and reliability in your data processing. With its user-friendly interface and extensive capabilities, JSON Repair empowers developers to seamlessly integrate JSON repair into their workflows.

github

: 135

mcp-omnisearch

mcp-omnisearch is a Model Context Protocol (MCP) server that acts as a unified gateway to multiple search providers and AI tools. It integrates Tavily, Perplexity, Kagi, Jina AI, Brave, Exa AI, and Firecrawl to offer a wide range of search, AI response, content processing, and enhancement features through a single interface. The server provides powerful search capabilities, AI response generation, content extraction, summarization, web scraping, structured data extraction, and more. It is designed to work flexibly with the API keys available, enabling users to activate only the providers they have keys for and easily add more as needed.

github

: 195

ai-gateway

LangDB AI Gateway is an open-source enterprise AI gateway built in Rust. It provides a unified interface to all LLMs using the OpenAI API format, focusing on high performance, enterprise readiness, and data control. The gateway offers features like comprehensive usage analytics, cost tracking, rate limiting, data ownership, and detailed logging. It supports various LLM providers and provides OpenAI-compatible endpoints for chat completions, model listing, embeddings generation, and image generation. Users can configure advanced settings, such as rate limiting, cost control, dynamic model routing, and observability with OpenTelemetry tracing. The gateway can be run with Docker Compose and integrated with MCP tools for server communication.

github

: 663

LightRAG

LightRAG is a repository hosting the code for LightRAG, a system that supports seamless integration of custom knowledge graphs, Oracle Database 23ai, Neo4J for storage, and multiple file types. It includes features like entity deletion, batch insert, incremental insert, and graph visualization. LightRAG provides an API server implementation for RESTful API access to RAG operations, allowing users to interact with it through HTTP requests. The repository also includes evaluation scripts, code for reproducing results, and a comprehensive code structure.

github

: 20.6k

mcp-documentation-server

The mcp-documentation-server is a lightweight server application designed to serve documentation files for projects. It provides a simple and efficient way to host and access project documentation, making it easy for team members and stakeholders to find and reference important information. The server supports various file formats, such as markdown and HTML, and allows for easy navigation through the documentation. With mcp-documentation-server, teams can streamline their documentation process and ensure that project information is easily accessible to all involved parties.

github

: 205

aws-mcp

AWS MCP is a Model Context Protocol (MCP) server that facilitates interactions between AI assistants and AWS environments. It allows for natural language querying and management of AWS resources during conversations. The server supports multiple AWS profiles, SSO authentication, multi-region operations, and secure credential handling. Users can locally execute commands with their AWS credentials, enhancing the conversational experience with AWS resources.

github

: 118

langcorn

LangCorn is an API server that enables you to serve LangChain models and pipelines with ease, leveraging the power of FastAPI for a robust and efficient experience. It offers features such as easy deployment of LangChain models and pipelines, ready-to-use authentication functionality, high-performance FastAPI framework for serving requests, scalability and robustness for language processing applications, support for custom pipelines and processing, well-documented RESTful API endpoints, and asynchronous processing for faster response times.

github

: 821

supergateway

Supergateway is a tool that allows running MCP stdio-based servers over SSE (Server-Sent Events) with one command. It is useful for remote access, debugging, or connecting to SSE-based clients when your MCP server only speaks stdio. The tool supports running in SSE to Stdio mode as well, where it connects to a remote SSE server and exposes a local stdio interface for downstream clients. Supergateway can be used with ngrok to share local MCP servers with remote clients and can also be run in a Docker containerized deployment. It is designed with modularity in mind, ensuring compatibility and ease of use for AI tools exchanging data.

github

: 599

vim-ai

vim-ai is a plugin that adds Artificial Intelligence (AI) capabilities to Vim and Neovim. It allows users to generate code, edit text, and have interactive conversations with GPT models powered by OpenAI's API. The plugin uses OpenAI's API to generate responses, requiring users to set up an account and obtain an API key. It supports various commands for text generation, editing, and chat interactions, providing a seamless integration of AI features into the Vim text editor environment.

github

: 878

For similar tasks

Gmail-MCP-Server

github

: 126

UFO

UFO is a UI-focused dual-agent framework to fulfill user requests on Windows OS by seamlessly navigating and operating within individual or spanning multiple applications.

github

: 6.6k

For similar jobs

zep

Zep is a long-term memory service for AI Assistant apps. With Zep, you can provide AI assistants with the ability to recall past conversations, no matter how distant, while also reducing hallucinations, latency, and cost. Zep persists and recalls chat histories, and automatically generates summaries and other artifacts from these chat histories. It also embeds messages and summaries, enabling you to search Zep for relevant context from past conversations. Zep does all of this asyncronously, ensuring these operations don't impact your user's chat experience. Data is persisted to database, allowing you to scale out when growth demands. Zep also provides a simple, easy to use abstraction for document vector search called Document Collections. This is designed to complement Zep's core memory features, but is not designed to be a general purpose vector database. Zep allows you to be more intentional about constructing your prompt: 1. automatically adding a few recent messages, with the number customized for your app; 2. a summary of recent conversations prior to the messages above; 3. and/or contextually relevant summaries or messages surfaced from the entire chat session. 4. and/or relevant Business data from Zep Document Collections.

github

: 2.4k

doc2plan

doc2plan is a browser-based application that helps users create personalized learning plans by extracting content from documents. It features a Creator for manual or AI-assisted plan construction and a Viewer for interactive plan navigation. Users can extract chapters, key topics, generate quizzes, and track progress. The application includes AI-driven content extraction, quiz generation, progress tracking, plan import/export, assistant management, customizable settings, viewer chat with text-to-speech and speech-to-text support, and integration with various Retrieval-Augmented Generation (RAG) models. It aims to simplify the creation of comprehensive learning modules tailored to individual needs.

github

: 138

whatsapp-chatgpt

This repository contains a WhatsApp bot that utilizes OpenAI's GPT and DALL-E 2 to respond to user inputs. Users can interact with the bot through voice messages, which are transcribed and responded to. The bot requires Node.js, npm, an OpenAI API key, and a WhatsApp account. It uses Puppeteer to run a real instance of Whatsapp Web to avoid being blocked. However, there is a risk of being blocked by WhatsApp as it does not allow bots or unofficial clients on its platform. The bot is not free to use, and users will be charged by OpenAI for each request made.

github

: 3.4k

OmniSteward

OmniSteward is an AI-powered steward system based on large language models that can interact with users through voice or text to help control smart home devices and computer programs. It supports multi-turn dialogue, tool calling for complex tasks, multiple LLM models, voice recognition, smart home control, computer program management, online information retrieval, command line operations, and file management. The system is highly extensible, allowing users to customize and share their own tools.

github

: 66

chatgpt-wechat

ChatGPT-WeChat is a personal assistant application that can be safely used on WeChat through enterprise WeChat without the risk of being banned. The project is open source and free, with no paid sections or external traffic operations except for advertising on the author's public account '积木成楼'. It supports various features such as secure usage on WeChat, multi-channel customer service message integration, proxy support, session management, rapid message response, voice and image messaging, drawing capabilities, private data storage, plugin support, and more. Users can also develop their own capabilities following the rules provided. The project is currently in development with stable versions available for use.

github

: 996

mcp-agent

mcp-agent is a simple, composable framework designed to build agents using the Model Context Protocol. It handles the lifecycle of MCP server connections and implements patterns for building production-ready AI agents in a composable way. The framework also includes OpenAI's Swarm pattern for multi-agent orchestration in a model-agnostic manner, making it the simplest way to build robust agent applications. It is purpose-built for the shared protocol MCP, lightweight, and closer to an agent pattern library than a framework. mcp-agent allows developers to focus on the core business logic of their AI applications by handling mechanics such as server connections, working with LLMs, and supporting external signals like human input.

github

: 7.3k

Gmail-MCP-Server

github

: 126

Operit

Operit AI is a fully functional AI assistant application for mobile devices, running independently on Android devices with powerful tool invocation capabilities. It offers over 40 built-in tools for file system operations, HTTP requests, system operations, UI automation, and media processing. The app combines these tools with rich plugins to enable a wide range of tasks, from simple to complex, providing a comprehensive experience of a smartphone AI assistant.

github

: 1.6k

Gmail-MCP-Server

README:

Gmail AutoAuth MCP Server

Features

Installation & Authentication

Installing via Smithery

Installing Manually

Docker Support

Cloud Server Authentication

Setup Instructions for Cloud Environment

Available Tools

1. Send Email (send_email)

2. Draft Email (draft_email)

3. Read Email (read_email)

4. Search Emails (search_emails)

5. Modify Email (modify_email)

6. Delete Email (delete_email)

7. List Email Labels (list_email_labels)

8. Create Label (create_label)

9. Update Label (update_label)

10. Delete Label (delete_label)

11. Get or Create Label (get_or_create_label)

12. Batch Modify Emails (batch_modify_emails)

13. Batch Delete Emails (batch_delete_emails)

Advanced Search Syntax

Advanced Features

Email Content Extraction

International Character Support

Comprehensive Label Management

Batch Operations

Security Notes

Troubleshooting

Contributing

License

Support

For Tasks:

For Jobs:

Alternative AI tools for Gmail-MCP-Server

Similar Open Source Tools

Gmail-MCP-Server

minions

scylla

mcp

aiavatarkit

langchainrb

agentpress

json-repair

mcp-omnisearch

ai-gateway

LightRAG

mcp-documentation-server

aws-mcp

langcorn

supergateway

vim-ai

For similar tasks

Gmail-MCP-Server

UFO

For similar jobs

zep

doc2plan

whatsapp-chatgpt

OmniSteward

chatgpt-wechat

mcp-agent

Gmail-MCP-Server

Operit

1. Send Email (`send_email`)

2. Draft Email (`draft_email`)

3. Read Email (`read_email`)

4. Search Emails (`search_emails`)

5. Modify Email (`modify_email`)

6. Delete Email (`delete_email`)

7. List Email Labels (`list_email_labels`)

8. Create Label (`create_label`)

9. Update Label (`update_label`)

10. Delete Label (`delete_label`)

11. Get or Create Label (`get_or_create_label`)

12. Batch Modify Emails (`batch_modify_emails`)

13. Batch Delete Emails (`batch_delete_emails`)