Gmail MCP Server 9b12e579

MCP安全风控

提供方 JaviEzpeleta

安全风控 未标注 OAuth 授权 社区 / 第三方 Claude DesktopClaude

一个基于Model Context Protocol(MCP)的服务器,通过OAuth2认证使AI助手能够与Gmail交互,具有安全优先的设计。

一句话选型结论

按资料字段整理

Gmail MCP Server 9b12e579 属于安全风控类 MCP 服务器,传输方式未标注,OAuth 授权,可直接接入 Claude Desktop、Claude,没有现成安装命令,需按官方文档接入。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类安全风控 传输方式未标注 鉴权OAuth 授权 部署方式支持远程部署
GitHub 星标 0 仓库热度,无公开仓库时显示未标注
工具数 6 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

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

能力标签

支持客户端

适用场景

Gmail集成TypeScript本地部署AI助手邮件管理安全设计OAuth2认证

安装与配置

未标注 OAuth 授权
上游未给出传输方式
  1. 1
    准备运行环境

    确认你的客户端支持远程端点,并拿到服务地址。

  2. 2
    安装服务

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

  3. 3
    写入客户端配置

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

  4. 4
    验证是否可用

    连接成功后客户端会列出约 6 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
资产与漏洞排查

盘点资产、扫漏洞、看暴露面。

日志与审计

汇总日志、查异常行为。

合规检查

按规则检查配置与权限是否合规。

选择建议

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

值得选的地方

  • 资料标注 6 个工具,职责相对集中,接入后不容易误操作。
  • 已适配 Claude Desktop、Claude,换客户端不用重新研究配置。

先想清楚的地方

  • 远程端点依赖网络与服务方可用性,注意密钥与调用额度。
  • 没有现成安装命令,需要按官方文档自己填启动命令和参数。
  • 使用前要准备好OAuth 授权对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在安全风控场景里让模型直接调用外部能力的人。
  • 已经在用 Claude Desktop、Claude 的用户,接入路径最短。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

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

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Gmail MCP Server 9b12e579当前 6 未标注 支持远程部署 无 2026-05-17
Cyber Strike AI 75 未标注 未标注 无 2026-05-17
mcp-for-beginners 未标注 stdio · 本地进程 本地部署 有 2026-04-13
casdoor 未标注 stdio · 本地进程 本地部署 有 2026-04-12
kubeshark 未标注 stdio · 本地进程 本地部署 有 2026-04-11
Modelcontextprotocol C22988b0 未标注 stdio · 本地进程 本地部署 有 2026-05-17

服务器档案

安全风控
字段来自项目仓库与公开索引,中文说明由本站标注
提供方JaviEzpeleta上游标注的维护方 JaviEzpeleta
分类安全风控本站按上游分类展示
连接方式未标注上游未给出传输方式
鉴权方式OAuth 授权远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型支持远程部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

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

📧 Gmail MCP Server

A powerful MCP (Model Context Protocol) server that enables AI assistants to
interact with Gmail through OAuth2 authentication with safety-first design.
Built with TypeScript and designed for seamless integration with Claude Desktop
and other MCP-compatible clients.

📑 Table of Contents

  • Features
  • Prerequisites
  • Installation
  • Configuration
  • Google Cloud Setup
  • OAuth2 Credentials
  • Generate Refresh Token
  • Usage
  • Standalone Server
  • Claude Desktop Integration
  • Available Tools
  • Examples
  • Troubleshooting
  • Development

✨ Features

  • 🛡️ Safety First - Draft-only mode by default prevents accidental email sends
  • 📝 Smart Drafts - Create drafts for new emails and replies with custom content
  • 📬 List Emails - Retrieve recent emails with advanced filtering options
  • 📖 Get Email Details - Fetch complete email content including attachments info
  • 🔍 Search Emails - Use Gmail's powerful search syntax to find specific emails
  • ✉️ Send Emails - Direct sending (disabled by default, enable with caution)
  • 🔐 Secure OAuth2 - Industry-standard authentication with refresh token support
  • 🎯 Type-Safe - Full TypeScript implementation with strict typing
  • 🚀 High Performance - Optimized with parallel processing and smart caching

📋 Prerequisites

Before you begin, ensure you have:

  • Node.js 18.0 or higher
  • npm or yarn package manager
  • Google Account with Gmail enabled
  • Google Cloud Console access
  • Claude Desktop (optional, for integration)

📦 Installation

  1. Clone the repository:```bash
    git clone https://github.com/JaviEzpeleta/gmail-mcp-server.git
    cd gmail-mcp-server

2. **Install dependencies:**```bash
npm install
  1. Create environment file:```bash
    cp .env.example .env

> **🛡️ Security Note**: By default, direct email sending is disabled for safety. The server will create drafts instead, which you can review and send manually from Gmail.

## ⚙️ Configuration

### 1. Google Cloud Console Setup

1. **Create or select a project:**

   - Go to Google Cloud Console
   - Click on the project dropdown and select "New Project"
   - Give your project a name (e.g., "Gmail MCP Server")
   - Click "Create"

2. **Enable Gmail API:**
   - In the sidebar, navigate to **APIs & Services** → **Library**
   - Search for "Gmail API"
   - Click on **Gmail API** from the results
   - Click **Enable**
   - Wait for the API to be enabled (usually takes a few seconds)

### 2. Create OAuth2 Credentials

1. **Configure OAuth consent screen:**

   - Go to **APIs & Services** → **OAuth consent screen**
   - Select "External" user type (unless you have a Google Workspace account)
   - Fill in the required fields:
     - App name: "Gmail MCP Server"
     - User support email: Your email
     - Developer contact: Your email
   - Add scopes:
     - `https://www.googleapis.com/auth/gmail.readonly`
     - `https://www.googleapis.com/auth/gmail.send`
     - `https://www.googleapis.com/auth/gmail.modify`
   - Add test users (important!):
     - Add your Gmail address and any other accounts you want to use
   - Save and continue through all steps

2. **Create OAuth client:**
   - Go to **APIs & Services** → **Credentials**
   - Click **+ CREATE CREDENTIALS** → **OAuth client ID**
   - Application type: **Web application** ⚠️ (NOT Desktop app)
   - Name: "Gmail MCP Web Client"
   - **Configure Authorized redirect URIs:**
     - Click **+ ADD URI**
     - Add: `http://localhost:8765/oauth2callback` (default port)
     - If you plan to use a custom port, add: `http://localhost:YOUR_PORT/oauth2callback`
   - Click **Create**
   - **Download the credentials** (you'll see a download button or JSON option)
   - Save the `client_id` and `client_secret` from the downloaded file

> **⚠️ Important**: Desktop app type doesn't allow custom redirect URIs, but we need `localhost:PORT/oauth2callback` for the OAuth flow to work. That's why we use **Web application** instead.

### 3. Generate Refresh Token

1. **Add credentials to .env:**```bash
GMAIL_CLIENT_ID=your_client_id_here
GMAIL_CLIENT_SECRET=your_client_secret_here
GMAIL_REFRESH_TOKEN=
# Security: Keep this false unless you need direct sending
GMAIL_ALLOW_DIRECT_SEND=false
# OAuth setup port (must match the redirect URI you configured above)
OAUTH_REDIRECT_PORT=8765

> 💡 Port Configuration: The OAUTH_REDIRECT_PORT must match the port you configured in the Google Cloud Console redirect URI. If you used http://localhost:8765/oauth2callback, keep it as 8765. If you used a different port, update this value accordingly.

  1. Run the setup script:```bash
    npm run setup

or

npm run dev src/get-refresh-token-desktop.ts


3. **Authorize the application:**

   - A browser window will open automatically
   - Sign in with your Google account
   - Grant all requested permissions
   - You'll be redirected to a success page

4. **Save the refresh token:**
   - The terminal will display your refresh token
   - Copy the complete `GMAIL_REFRESH_TOKEN` value
   - Add it to your `.env` file

## 🚀 Usage

### Standalone Server

1. **Build the project:**```bash
npm run build
  1. Start the server:```bash
    npm start

The server will start and listen for MCP commands via stdio.

### Claude Desktop Integration

1. **Build the project first:**```bash
npm run build
  1. Locate Claude Desktop config:
  • macOS:
    ~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  1. Edit the configuration file:```json
    {
    "mcpServers": {
    "gmail": {
    "command": "node",
    "args": ["/absolute/path/to/gmail-mcp-server/dist/index.js"],
    "env": {
    "GMAIL_CLIENT_ID": "your_client_id",
    "GMAIL_CLIENT_SECRET": "your_client_secret",
    "GMAIL_REFRESH_TOKEN": "your_refresh_token",
    "GMAIL_ALLOW_DIRECT_SEND": "false"
    }
    }
    }
    }

4. **Restart Claude Desktop**

5. **Verify the connection:**
   - Open Claude Desktop
   - Look for the 🔌 icon indicating MCP connection
   - Try: "List my recent emails"

## 🛠️ Available Tools

> **🛡️ Safety Notice**: Tools marked with 🛡️ create drafts by default for your safety. Direct sending tools marked with 🚨 are disabled by default.

### 📬 list_emails

List recent emails with optional filtering.

**Parameters:**

- `maxResults` (number, 1-100): Maximum emails to return (default: 10)
- `query` (string): Gmail search query (e.g., "is:unread")
- `includeSpamTrash` (boolean): Include SPAM/TRASH folders (default: false)

**Example:**```
List my 5 most recent unread emails

📖 get_email_details

Get complete details and content of a specific email.

Parameters:

  • emailId (string, required): The email ID to retrieve
  • format (string): Level of detail - "full", "minimal", or "metadata"
    (default: "full")

Example:```
Get the full content of email ID 18abc123def


### 🛡️ create_draft

Create an email draft with optional CC/BCC recipients (recommended for AI assistants).

**Parameters:**

- `to` (string, required): Recipient email address
- `subject` (string, required): Email subject
- `body` (string, required): Email body (plain text or HTML)
- `cc` (string): CC recipients (comma-separated)
- `bcc` (string): BCC recipients (comma-separated)

**Example:**```
Create a draft email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM"

🚨 send_email (Disabled by Default)

Send an email directly with optional CC/BCC recipients.

⚠️ Security Warning: This tool is disabled by default. Set GMAIL_ALLOW_DIRECT_SEND=true to enable.

Parameters:

  • to (string, required): Recipient email address
  • subject (string, required): Email subject
  • body (string, required): Email body (plain text or HTML)
  • cc (string): CC recipients (comma-separated)
  • bcc (string): BCC recipients (comma-separated)

Example:```
Send an email to john@example.com with subject "Meeting Tomorrow" and body "Let's meet at 10 AM"


### 🔍 search_emails

Search emails using Gmail's advanced search syntax.

**Parameters:**

- `query` (string, required): Gmail search query
- `maxResults` (number, 1-100): Maximum results (default: 10)
- `includeSpamTrash` (boolean): Include SPAM/TRASH (default: false)

**Example Gmail search queries:**

- `from:user@example.com` - Emails from a specific sender
- `subject:"important meeting"` - Emails with exact phrase in subject
- `has:attachment` - Emails with attachments
- `is:unread` - Unread emails
- `newer_than:2d` - Emails from last 2 days
- `label:work` - Emails with specific label

### 🛡️ find_and_draft_reply

Find the latest email from a sender and create a draft reply with optional custom content.

**Parameters:**

- `senderName` (string, required): Sender name or email address
- `replyBody` (string, optional): Custom reply content (template used if not provided)

**Example:**```
Create a draft reply to the latest email from John Smith saying "Thanks for your message. I'll get back to you soon."

📚 Examples

Basic Usage Examples

List recent emails:```
Show me my 10 most recent emails


**Search for specific emails:**```
Search for emails from alice@example.com with attachments

Create a draft email:```
Create a draft email to bob@example.com saying "Thanks for your help!"


**Create a draft reply:**```
Draft a reply to the latest email from support@company.com

Advanced Usage Examples

Complex search:```
Find all unread emails from the last week with "invoice" in the subject


**Draft with CC:**```
Create a draft email to team@company.com with CC to manager@company.com about the project update

Get email details:```
Show me the full content of the most recent email from my boss


## 🔧 Troubleshooting

### Common Issues and Solutions

#### ❌ Error: Missing required environment variables

**Solution:** Ensure all required environment variables are set in your `.env` file:

- `GMAIL_CLIENT_ID`
- `GMAIL_CLIENT_SECRET`
- `GMAIL_REFRESH_TOKEN`
- `GMAIL_ALLOW_DIRECT_SEND` (optional, defaults to `false`)
- `OAUTH_REDIRECT_PORT` (optional, defaults to `8765`)

#### ❌ Error: redirect_uri_mismatch

**Problem:** OAuth setup fails with "The redirect URI in the request does not match the ones authorized for the OAuth client."

**Solution:**
1. Go to Google Cloud Console → APIs & Services → Credentials
2. Click on your OAuth client
3. In "Authorized redirect URIs", ensure you have: `http://localhost:8765/oauth2callback`
4. If using a custom port, add: `http://localhost:YOUR_PORT/oauth2callback`
5. Make sure your `.env` file has the matching `OAUTH_REDIRECT_PORT=8765`
6. **Important**: OAuth client must be **Web application** type, not Desktop app

> This error commonly occurs when following old documentation that suggests using "Desktop app" type, which doesn't support custom redirect URIs.

#### 🛡️ Security: Direct email sending is disabled

**This is normal and safe behavior.** By default, the server creates drafts instead of sending emails directly.

**Solutions:**
- **Recommended**: Use `create_draft` tool instead of `send_email`
- **Alternative**: Set `GMAIL_ALLOW_DIRECT_SEND=true` in your `.env` file (not recommended for AI assistants)

#### ❌ Error 403: access_denied

**Solution:**

1. Go to Google Cloud Console → OAuth consent screen
2. Add your email as a test user
3. Re-run the token generation process

#### ❌ Error: invalid_grant

**Solution:** Your refresh token has expired or is invalid

1. Delete the old refresh token from `.env`
2. Run `npm run setup` again
3. Complete the authorization flow
4. Update `.env` with the new token

#### ❌ Gmail API not enabled

**Solution:**

1. Go to Google Cloud Console
2. Navigate to APIs & Services → Library
3. Search for "Gmail API"
4. Click Enable

#### ❌ Claude Desktop doesn't show the MCP server

**Solution:**

1. Verify the config file path is correct
2. Ensure all paths in the config are absolute paths
3. Check that the built files exist in `dist/`
4. Restart Claude Desktop completely
5. Check Claude Desktop logs for errors

#### ❌ Rate limit exceeded

**Solution:**

- Gmail API has quotas (250 quota units per user per second)
- Implement exponential backoff for retries
- Reduce the number of parallel requests

## 🔒 Security Guidelines

### Draft-First Approach

This server implements a **safety-first design** to prevent accidental email sends:

- **Default behavior**: Creates drafts that require manual review
- **Protection**: `send_email` tool is disabled by default
- **User control**: Explicit environment variable required for direct sending

### Recommended Usage

✅ **Safe for AI assistants:**
- `create_draft` - Creates email drafts
- `find_and_draft_reply` - Creates reply drafts
- `list_emails`, `search_emails`, `get_email_details` - Read-only operations

⚠️ **Use with caution:**
- `send_email` - Only enable if you fully trust the AI assistant and understand the risks

### Best Practices

1. **Keep `GMAIL_ALLOW_DIRECT_SEND=false`** unless absolutely necessary
2. **Review all drafts** before sending manually from Gmail
3. **Test thoroughly** in a safe environment before production use
4. **Monitor usage** and check for unexpected behavior

## 🔨 Development

### Available Scripts```bash
# Development with hot reload
npm run dev

# Build TypeScript to JavaScript
npm run build

# Start production server
npm start

# Generate OAuth refresh token
npm run setup

# Run tests
npm test

# Lint code
npm run lint

Project Structure```

gmail-mcp-server/
├── src/
│ ├── index.ts # Main server implementation
│ └── get-refresh-token-desktop.ts # OAuth setup utility
├── dist/ # Compiled JavaScript (generated)
├── examples/ # Usage examples
├── docs/ # Additional documentation
├── .env.example # Environment variables template
├── tsconfig.json # TypeScript configuration
├── package.json # Project dependencies
└── README.md # This file


### Testing

Test the connection and basic functionality:```bash
# Test Gmail connection
npm run dev test-gmail-connection.ts

# Test with MCP client
npm run dev test-list-emails.js

🤝 Contributing

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

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/AmazingFeature)
  3. Commit your changes (git commit -m 'Add some AmazingFeature')
  4. Push to the branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file
for details.

🙏 Acknowledgments

  • Google Gmail API for email
    functionality
  • Model Context Protocol for the MCP
    specification
  • Anthropic for Claude and MCP development

📞 Support

For issues, questions, or suggestions:

  • Open an issue on
    GitHub
  • Check existing issues for solutions
  • Read the
    Gmail API documentation

Made with ❤️ by Javi Ezpeleta

常见问题

8 问
答案由本站依据条目字段整理,不引用上游原文
Gmail MCP Server 9b12e579 怎么安装?

资料没有给出安装命令,请到官方仓库或文档按说明接入;这类条目多数是生态应用,或尚未发布可安装包。

Gmail MCP Server 9b12e579 怎么在 Claude Desktop、Claude 里配置?

它的传输方式未标注,在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,配置才会生效。

Gmail MCP Server 9b12e579 收费吗?

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

Gmail MCP Server 9b12e579 需要 API Key 吗?

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

Gmail MCP Server 9b12e579 支持哪些客户端?

资料标注支持 Claude Desktop、Claude;其他客户端只要能配置 MCP Server,也能用同样的命令或地址接入。

Gmail MCP Server 9b12e579 能提供哪些能力?

资料显示约 6 个工具;能力标签包括 Gmail集成、TypeScript、Claude、邮件管理。具体工具清单以官方文档为准。

Gmail MCP Server 9b12e579 需要什么运行环境?

属于远程端点,不需要在本地装运行时。

Gmail MCP Server 9b12e579 是本地还是远程?

它是远程端点,连服务地址即可。

热门专题

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

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