Gmail 4f58f5b2

MCP办公协作

提供方 未标注

办公协作 stdio · 本地进程 OAuth 授权 社区 / 第三方
查看接入方式

全面解析Gmail Imap MCPMCP Server的核心功能、安装配置和实用案例。作为顶级Model Context Protocol服务器,Gmail Imap MCP能让AI助手访问实时数据、执行操作,为您提供更智能的工作体验和自动化解决方案。

一句话选型结论

按资料字段整理

Gmail 4f58f5b2 属于办公协作类 MCP 服务器,stdio · 本地进程,OAuth 授权,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类办公协作 传输方式stdio · 本地进程 鉴权OAuth 授权 部署方式本地部署
GitHub 星标 未标注 仓库热度,无公开仓库时显示未标注
工具数 未标注 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

办公协作
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量未标注暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

安装与配置

stdio · 本地进程 OAuth 授权
客户端在本机拉起子进程,数据不出本机
pip install gmail-imap-mcp-server

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Python,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后随便调一个只读工具,确认能返回结果,再接入正式流程。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
日程与消息

查日程、发消息、约会议。

表单与审批

填表单、走审批流。

团队协作

同步任务、汇总进展。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 资料没标注工具数量,实际能力要装好后确认。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在办公协作场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Gmail 4f58f5b2当前 未标注 stdio · 本地进程 本地部署 有 2026-05-17
CowAgent 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Karakeep MCP 未标注 未标注 未标注 无 2026-05-17
agentscope 未标注 stdio · 本地进程 本地部署 有 2026-04-11
note-gen 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Everywhere 未标注 stdio · 本地进程 本地部署 有 2026-04-12

服务器档案

办公协作
字段来自项目仓库与公开索引,中文说明由本站标注
提供方未标注上游标注的维护方 未标注
分类办公协作本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · Python本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

17.2 KB
来自项目仓库与上游目录的原文,未做删改

Gmail IMAP MCP Server

A Model Context Protocol (MCP) server for Gmail integration using IMAP. This server allows AI assistants to interact with Gmail accounts, providing functionality to read, search, and manage emails.

Features

  • OAuth2 authentication with Gmail
  • Read emails from Gmail accounts
  • Search emails with advanced query options
  • View unread emails
  • Send emails with attachments
  • Manage labels (create, delete, list)
  • Move emails between labels
  • Download attachments
  • Mark emails as read/unread
  • Support for multiple Gmail accounts
  • Integration with AI assistants through MCP

Prerequisites

Before running the Gmail IMAP MCP server, ensure you have the following:

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

Installation

Install from source

  1. Clone the repository:git clone https://github.com/yourusername/gmail-imap-mcp.git cd gmail-imap-mcp

  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 the package:pip install -e .

Setup Google Cloud Project

  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:
    - Navigate to "APIs & Services" > "Library"
    - Search for "Gmail API" and enable it
  4. Create OAuth 2.0 credentials:
    - Go to "APIs & Services" > "Credentials"
    - Click "Create Credentials" > "OAuth client ID"
    - Choose "Desktop app" as application type
    - Download the client configuration file
  5. Save the downloaded file as client_secret.json in the credentials directory:mkdir -p ~/.gmail_imap_mcp_credentials # Move the downloaded file to ~/.gmail_imap_mcp_credentials/client_secret.json

Architecture and Implementation Details

Credential Storage

The Gmail IMAP MCP server stores OAuth2 credentials in the user's home directory at ~/.gmail_imap_mcp_credentials/. This approach offers several advantages:

  1. Security: Credentials are stored in a user-specific location rather than in the application directory
  2. Persistence: Credentials persist across different sessions and application restarts
  3. Compatibility: Avoids permission issues on read-only file systems

The credentials directory contains:
- client_secret.json: Your OAuth client credentials from Google Cloud Console
- Token files for each authenticated Gmail account (format: token_{email_address}.json)

IMAP Implementation

The server uses Python's imaplib2 library for IMAP operations with Gmail. Key implementation details include:

  1. Connection: Secure connection to Gmail's IMAP server (imap.gmail.com) on port 993
  2. Authentication: OAuth2 authentication using XOAUTH2 mechanism
  3. Email Retrieval: Emails are retrieved using RFC822 format and parsed with Python's email module
  4. Label Management: Gmail labels are managed through IMAP mailbox operations

Email ID Format

Email IDs in the system follow this format:```
email://message/{account}{mailbox}{id}


Where:
- `{account}`: The Gmail account address
- `{mailbox}`: The mailbox/label containing the email
- `{id}`: The unique IMAP ID of the email

This format allows the system to uniquely identify emails across different accounts and mailboxes.

## Usage

### Starting the Server

Run the Gmail IMAP MCP server:```
gmail-imap-mcp

Authenticating Gmail Accounts

  1. Use the authenticate-gmail tool with your email address
  2. Follow the OAuth2 authentication flow in your browser
  3. Once authenticated, the server will store your credentials for future use

Available Tools and Examples

The Gmail IMAP MCP server provides a comprehensive set of tools for interacting with Gmail accounts. Below is a detailed list of all available tools along with examples of how to use them.

Authentication

1. authenticate-gmail

Authenticate a Gmail account to use with the MCP server.

Parameters:
- email: Email address to authenticate

Example:```json
{
"name": "authenticate-gmail",
"arguments": {
"email": "your.email@gmail.com"
}
}


### Email Retrieval and Search

#### 2. search-emails
Search for emails in a Gmail account using various search criteria.

**Parameters:**
- `account`: Email account to search in
- `mailbox`: Mailbox to search in (default: INBOX)
- `query`: Search query
- `limit`: Maximum number of emails to return (default: 10)

**Example - Search for emails from a specific sender:**```json
{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "mailbox": "INBOX",
    "query": "from:sender@example.com",
    "limit": 5
  }
}

Example - Search for emails with a specific subject:```json
{
"name": "search-emails",
"arguments": {
"account": "your.email@gmail.com",
"query": "subject:\"Meeting Invitation\""
}
}


**Example - Search for emails with specific text in the body:**```json
{
  "name": "search-emails",
  "arguments": {
    "account": "your.email@gmail.com",
    "query": "TEXT \"project update\""
  }
}

3. get-unread-emails

Get unread emails from a Gmail account.

Parameters:
- account: Email account to get emails from
- mailbox: Mailbox to get emails from (default: INBOX)
- limit: Maximum number of emails to return (default: 10)

Example:```json
{
"name": "get-unread-emails",
"arguments": {
"account": "your.email@gmail.com",
"limit": 20
}
}


### Email Composition and Sending

#### 4. send-email
Send an email from a Gmail account with optional attachments and HTML content.

**Parameters:**
- `account`: Email account to send from
- `to`: Recipient email address(es), comma-separated for multiple
- `subject`: Email subject
- `body`: Plain text email body
- `cc`: Carbon copy recipients (optional)
- `bcc`: Blind carbon copy recipients (optional)
- `html_body`: HTML version of the email body (optional)
- `attachments`: List of attachment objects (optional)
  - Each attachment object requires:
    - `path`: Path to the file
    - `filename`: Custom filename (optional)
    - `content_type`: MIME type (optional)

**Example - Simple email:**```json
{
  "name": "send-email",
  "arguments": {
    "account": "your.email@gmail.com",
    "to": "recipient@example.com",
    "subject": "Hello from Gmail MCP",
    "body": "This is a test email sent via the Gmail IMAP MCP server."
  }
}

Example - Email with CC, BCC, and HTML content:```json
{
"name": "send-email",
"arguments": {
"account": "your.email@gmail.com",
"to": "recipient@example.com",
"subject": "Meeting Agenda",
"body": "Please find the agenda for our upcoming meeting.",
"cc": "manager@example.com",
"bcc": "archive@example.com",
"html_body": "<h1>Meeting Agenda</h1><p>Please find the agenda for our <b>upcoming meeting</b>.</p>"
}
}


**Example - Email with attachment:**```json
{
  &quot;name&quot;: &quot;send-email&quot;,
  &quot;arguments&quot;: {
    &quot;account&quot;: &quot;your.email@gmail.com&quot;,
    &quot;to&quot;: &quot;recipient@example.com&quot;,
    &quot;subject&quot;: &quot;Document Attached&quot;,
    &quot;body&quot;: &quot;Please find the attached document.&quot;,
    &quot;attachments&quot;: [
      {
        &quot;path&quot;: &quot;/path/to/document.pdf&quot;,
        &quot;filename&quot;: &quot;important_document.pdf&quot;,
        &quot;content_type&quot;: &quot;application/pdf&quot;
      }
    ]
  }
}

Label Management

5. create-label

Create a new label/mailbox in a Gmail account.

Parameters:
- account: Email account to create label in
- label_name: Name of the label to create

Example:```json
{
"name": "create-label",
"arguments": {
"account": "your.email@gmail.com",
"label_name": "ProjectX"
}
}


#### 6. delete-label
Delete a label/mailbox from a Gmail account.

**Parameters:**
- `account`: Email account to delete label from
- `label_name`: Name of the label to delete

**Example:**```json
{
  &quot;name&quot;: &quot;delete-label&quot;,
  &quot;arguments&quot;: {
    &quot;account&quot;: &quot;your.email@gmail.com&quot;,
    &quot;label_name&quot;: &quot;OldProject&quot;
  }
}

7. list-labels

List all labels/mailboxes in a Gmail account.

Parameters:
- account: Email account to list labels from

Example:```json
{
"name": "list-labels",
"arguments": {
"account": "your.email@gmail.com"
}
}


### Email Organization

#### 8. move-email
Move an email from one label/mailbox to another.

**Parameters:**
- `account`: Email account
- `email_id`: Email ID to move (format: `email://message/{account}_{mailbox}_{id}`)
- `source_mailbox`: Source mailbox
- `target_mailbox`: Target mailbox

**Example:**```json
{
  &quot;name&quot;: &quot;move-email&quot;,
  &quot;arguments&quot;: {
    &quot;account&quot;: &quot;your.email@gmail.com&quot;,
    &quot;email_id&quot;: &quot;email://message/your.email@gmail.com_INBOX_12345&quot;,
    &quot;source_mailbox&quot;: &quot;INBOX&quot;,
    &quot;target_mailbox&quot;: &quot;ProjectX&quot;
  }
}

Attachment Handling

9. download-attachment

Download an attachment from an email.

Parameters:
- account: Email account
- email_id: Email ID (format: email://message/{account}_{mailbox}_{id})
- attachment_index: Index of the attachment to download (0-based)
- mailbox: Mailbox containing the email (default: INBOX)
- download_dir: Directory to save the attachment to (default: "downloads")

Example:```json
{
"name": "download-attachment",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345",
"attachment_index": 0,
"download_dir": "my_attachments"
}
}


### Email Status Management

#### 10. mark-as-read
Mark an email as read.

**Parameters:**
- `account`: Email account
- `email_id`: Email ID (format: `email://message/{account}_{mailbox}_{id}`)
- `mailbox`: Mailbox containing the email (default: INBOX)

**Example:**```json
{
  &quot;name&quot;: &quot;mark-as-read&quot;,
  &quot;arguments&quot;: {
    &quot;account&quot;: &quot;your.email@gmail.com&quot;,
    &quot;email_id&quot;: &quot;email://message/your.email@gmail.com_INBOX_12345&quot;
  }
}

11. mark-as-unread

Mark an email as unread.

Parameters:
- account: Email account
- email_id: Email ID (format: email://message/{account}_{mailbox}_{id})
- mailbox: Mailbox containing the email (default: INBOX)

Example:```json
{
"name": "mark-as-unread",
"arguments": {
"account": "your.email@gmail.com",
"email_id": "email://message/your.email@gmail.com_INBOX_12345"
}
}


## Available Prompts

The server provides the following prompts for AI assistants to use:

### 1. summarize-emails
Creates a summary of recent emails.

**Parameters:**
- `account`: Email account to summarize
- `mailbox`: Mailbox to summarize (default: INBOX)
- `count`: Number of emails to summarize (default: 5)

**Example:**```json
{
  &quot;name&quot;: &quot;summarize-emails&quot;,
  &quot;arguments&quot;: {
    &quot;account&quot;: &quot;your.email@gmail.com&quot;,
    &quot;mailbox&quot;: &quot;INBOX&quot;,
    &quot;count&quot;: 10
  }
}

Integration with AI Assistants

The Gmail IMAP MCP server can be integrated with AI assistants that support the Model Context Protocol (MCP). Here's a typical workflow:

  1. Authentication: The AI assistant uses the authenticate-gmail tool to authenticate the user's Gmail account.

  2. Email Management: The assistant can retrieve, search, and manage emails using the various tools provided by the server.

  3. Email Composition: The assistant can help draft and send emails based on user instructions.

  4. Email Organization: The assistant can help organize emails by creating labels, moving emails between labels, and marking emails as read/unread.

  5. Email Summarization: The assistant can summarize emails using the summarize-emails prompt.

Connecting with AI Assistants

Claude Desktop

To connect the Gmail IMAP MCP server with Claude Desktop:

  1. Start the Gmail IMAP MCP server:bash python -m gmail_imap_mcp.server

  2. Open Claude Desktop and navigate to Settings (gear icon)

  3. Scroll down to the "Advanced" section and click on "Edit MCP Configuration"

  4. Add the Gmail IMAP MCP server configuration:json { &quot;servers&quot;: [ { &quot;name&quot;: &quot;Gmail IMAP&quot;, &quot;url&quot;: &quot;http://localhost:8080&quot;, &quot;tools&quot;: [ &quot;list-emails&quot;, &quot;get-email&quot;, &quot;search-emails&quot;, &quot;send-email&quot;, &quot;list-mailboxes&quot;, &quot;create-label&quot;, &quot;move-email&quot;, &quot;mark-as-read&quot;, &quot;download-attachment&quot; ] } ] }

  5. Click "Save" and restart Claude Desktop

  6. You can now ask Claude to interact with your Gmail account, for example:
    - "Show me my unread emails"
    - "Send an email to [recipient] about [subject]"
    - "Create a new label called 'Important'"
    - "Move the email from [sender] to the 'Important' label"

Windsurf IDE

To connect the Gmail IMAP MCP server with Windsurf IDE:

  1. Start the Gmail IMAP MCP server:bash python -m gmail_imap_mcp.server

  2. Open Windsurf IDE and navigate to Settings

  3. Find the "AI Flow" or "MCP Configuration" section

  4. Add the Gmail IMAP MCP server configuration:json { &quot;servers&quot;: [ { &quot;name&quot;: &quot;Gmail IMAP&quot;, &quot;url&quot;: &quot;http://localhost:8080&quot;, &quot;tools&quot;: [ &quot;list-emails&quot;, &quot;get-email&quot;, &quot;search-emails&quot;, &quot;send-email&quot;, &quot;list-mailboxes&quot;, &quot;create-label&quot;, &quot;move-email&quot;, &quot;mark-as-read&quot;, &quot;download-attachment&quot; ] } ] }

  5. Save the settings and restart Windsurf if necessary

  6. You can now ask Cascade (Windsurf's AI assistant) to interact with your Gmail account using the same commands as with Claude Desktop

Common Use Cases

1. Email Triage```

Assistant: I'll help you triage your unread emails.
User: Yes, please check my unread emails.
Assistant: [Uses get-unread-emails tool]
Assistant: You have 5 unread emails. The most urgent appears to be from your boss about the quarterly report due tomorrow.
User: Mark that as read and I'll look at it right away.
Assistant: [Uses mark-as-read tool]


### 2. Email Search and Organization```
Assistant: Would you like me to find specific emails for you?
User: Yes, find all emails from john@example.com about the project budget.
Assistant: [Uses search-emails tool with query &quot;from:john@example.com project budget&quot;]
Assistant: I found 3 emails from John about the project budget. Would you like me to create a label for these?
User: Yes, create a &quot;Budget&quot; label and move them there.
Assistant: [Uses create-label tool followed by move-email tool for each email]

3. Email Composition```

Assistant: Would you like me to draft an email for you?
User: Yes, write a follow-up email to the marketing team about our campaign results.
Assistant: [Drafts email content]
Assistant: Here's a draft. Would you like me to send it?
User: Yes, but add Sarah in CC.
Assistant: [Uses send-email tool with the drafted content and CC]


## Gmail-Specific Considerations

### Label Naming Conventions

Gmail has specific requirements for label names:

1. Label names are case-sensitive
2. Some special characters may not be allowed
3. System labels (like INBOX, Sent, Trash) cannot be created or deleted
4. Nested labels are represented with a forward slash (e.g., &quot;Projects/ProjectX&quot;)

### Email ID Format

The email ID format used by this MCP server is:```
email://message/{account}_{mailbox}_{id}

When using tools that require an email ID (like mark-as-read or move-email), make sure to use the complete resource URI returned by email retrieval tools.

Security Considerations

  • The server stores OAuth2 credentials locally in the ~/.gmail_imap_mcp_credentials directory
  • Never share your client_secret.json or token files
  • The server only connects to Gmail's IMAP server using secure connections
  • Email attachments are downloaded to the downloads directory by default
  • Be cautious when using the server in shared environments to protect email data

Troubleshooting

Authentication Issues

  • Ensure your client_secret.json is correctly placed in the ~/.gmail_imap_mcp_credentials directory
  • Check that you've enabled the Gmail API in your Google Cloud Project
  • Try re-authenticating if your token has expired
  • If you see "Read-only file system" errors, ensure the credentials directory is writable

Connection Issues

  • Verify your internet connection
  • Ensure that your Google account doesn't have any security restrictions that might block IMAP access
  • Check if you need to enable "Less secure app access" in your Google account settings

Email Sending Issues

  • Verify that your Gmail account allows SMTP access
  • Check if you need to enable "Less secure app access" in your Google account settings
  • Ensure attachments are not too large (Gmail has a 25MB limit)

Label Management Issues

  • If creating labels fails, check if the label already exists (case-sensitive)
  • System labels cannot be created or deleted
  • Ensure label names follow Gmail's naming conventions

Email Movement Issues

  • If moving emails between labels fails, ensure both source and target labels exist
  • Check that the email ID format is correct
  • Verify that you have sufficient permissions to modify the email

Email ID Parsing Issues

  • If operations on email IDs fail, ensure you're using the complete resource URI
  • The system parses the last part of the URI as the actual email ID
  • Format should be: email://message/{account}_{mailbox}_{id}

License

MIT License

Support

For issues and feature requests, please open an issue on the GitHub repository.

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Gmail 4f58f5b2 怎么安装?

在客户端按下面的安装命令接入:pip install gmail-imap-mcp-server。装完在客户端配置里引用同一个包或端点。

Gmail 4f58f5b2 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Gmail 4f58f5b2 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Gmail 4f58f5b2 需要 API Key 吗?

资料标注需要OAuth 授权认证,使用前准备好对应凭据,并按最小权限配置。

Gmail 4f58f5b2 能提供哪些能力?

资料显示能力标签包括 邮件管理、Gmail集成、Python、OAuth认证、STDIO。具体工具清单以官方文档为准。

Gmail 4f58f5b2 需要什么运行环境?

运行时为 Python;属于本地进程,需要在本机装好运行环境。

Gmail 4f58f5b2 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。