Gmail MCP Manager

Gmail MCP服务器

](https://badge.fury.io/js/@cristiano-morgante%2Fgmail-mcp-manager)  

A完整 MCP（模型上下文提供程序）服务器 用于Gmail API管理，具有OAuth2身份验证和Context7集成。该套餐同时提供 CLI接口 以及a 程序化API 用于通过自动文档集成管理Gmail操作。

✨ 特性

• 🔐 OAuth2身份验证 具有自动令牌刷新功能
• 📧 完整的电子邮件管理 （发送、阅读、搜索、组织）
• 📝 草案管理 （创建、更新、发送草稿）
• 🏷️ 标签管理 和组织
• 📦 批量操作 用于高效的批量操作
• 🧵 线程管理 用于对话处理
• 📚 上下文7集成 用于自动记录
• 🖥️ CLI接口 用于终端使用
• 📦 NPM包 用于程序集成
• 🔒 安全令牌存储 具有适当的权限
• ⚡ TypeScript支持 具有完整的类型定义

🚀 快速开始

安装

# Install globally for CLI usage
npm install -g @cristiano-morgante/gmail-mcp-manager

# Or install locally for programmatic usage
npm install @cristiano-morgante/gmail-mcp-manager

设置

1. 获取Google OAuth2凭据

- 首选 谷歌云控制台 - 创建新项目或选择现有项目 - 启用Gmail API - 创建OAuth2凭据（桌面应用程序） - 下载凭据

1. 配置环境

   # Copy the example environment file
   cp .env.example .env

   # Edit .env with your credentials
   GOOGLE_CLIENT_ID=your_client_id_here
   GOOGLE_CLIENT_SECRET=your_client_secret_here

1. 验证

   # CLI authentication
   gmail-mcp auth login

   # Or programmatically (will prompt for auth)
   node -e "import('@cristiano-morgante/gmail-mcp-manager').then(({createFromEnvironment}) => createFromEnvironment().initialize())"

📖 用法

CLI使用情况

认证

# Login with Google OAuth2
gmail-mcp auth login

# Check authentication status
gmail-mcp auth status

# Logout and revoke tokens
gmail-mcp auth logout

消息管理

# List recent messages
gmail-mcp messages list

# List unread messages
gmail-mcp messages list --query "is:unread"

# List messages with attachments
gmail-mcp messages list --query "has:attachment" --max 20

# Get specific message details
gmail-mcp messages get MESSAGE_ID

# Send an email (interactive)
gmail-mcp messages send

草案管理

# List drafts
gmail-mcp drafts list

# Create a new draft (interactive)
gmail-mcp drafts create

# Send a draft
gmail-mcp drafts send DRAFT_ID

批量操作

# Mark messages as read
gmail-mcp batch mark-read MSG_ID1 MSG_ID2 MSG_ID3

# Archive messages
gmail-mcp batch archive MSG_ID1 MSG_ID2

实用程序命令

# List all labels
gmail-mcp labels

# Show email statistics
gmail-mcp stats

# Context7 documentation
gmail-mcp context7 status
gmail-mcp context7 get sendMessage
gmail-mcp context7 clear-cache

程序化使用

基础示例

import { createFromEnvironment } from '@cristiano-morgante/gmail-mcp-manager';

async function example() {
  // Create manager from environment variables
  const manager = createFromEnvironment();
  
  // Initialize (handles authentication)
  await manager.initialize();
  
  // List recent messages
  const messages = await manager.listMessages({
    maxResults: 10,
    query: 'is:unread'
  });
  
  // Send an email
  const email = {
    to: ['recipient@example.com'],
    subject: 'Hello from Gmail MCP!',
    body: 'This email was sent using Gmail MCP Server.',
    isHtml: false
  };
  
  const sentMessage = await manager.sendMessage(email);
  console.log('Email sent:', sentMessage.id);
}

高级配置

import { GmailMCPManager, GMAIL_SCOPES } from '@cristiano-morgante/gmail-mcp-manager';

const config = {
  oauth2: {
    clientId: 'your_client_id',
    clientSecret: 'your_client_secret',
    redirectUri: 'http://localhost:3000/oauth2callback',
    scopes: [GMAIL_SCOPES.MODIFY, GMAIL_SCOPES.COMPOSE]
  },
  defaultUserId: 'me',
  context7Enabled: true,
  tokenStoragePath: './custom-tokens.json'
};

const manager = new GmailMCPManager(config);
await manager.initialize();

上下文7集成

// Get documentation for specific operations
const docs = await manager.getDocumentation('sendMessage', 'HTML email');
console.log('Documentation:', docs.documentation);
console.log('Examples:', docs.examples);

// Get documentation as code comments
const comments = await manager.getDocumentationAsComments('listMessages');
console.log(comments);

🔧 配置

环境变量

Gmail范围

可用范围（使用 GMAIL_SCOPES 常数）：

• GMAIL_SCOPES.READONLY -只读访问
• GMAIL_SCOPES.MODIFY -读/写访问（推荐）
• GMAIL_SCOPES.COMPOSE -撰写和发送电子邮件
• GMAIL_SCOPES.SEND -仅发送电子邮件
• GMAIL_SCOPES.LABELS -管理标签
• GMAIL_SCOPES.SETTINGS_BASIC -基本设置访问

📚 api参考

GmailMCPManager

核心方法

// Initialization
await manager.initialize(): Promise

// Message operations
await manager.listMessages(options?: EmailListOptions): Promise

await manager.getMessage(messageId: string, format?: 'full' | 'metadata' | 'minimal'): Promise
await manager.sendMessage(email: EmailComposition): Promise

// Draft operations
await manager.createDraft(email: EmailComposition): Promise
await manager.updateDraft(draftId: string, email: EmailComposition): Promise
await manager.sendDraft(draftId: string): Promise
await manager.listDrafts(maxResults?: number, pageToken?: string): Promise

// Batch operations
await manager.performBatchOperation(operation: BatchOperation): Promise

// Utility methods
await manager.getLabels(): Promise

await manager.getEmailStats(): Promise
await manager.getThread(threadId: string, format?: string): Promise
await manager.listThreads(options?: EmailListOptions): Promise

// Authentication
await manager.logout(): Promise
await manager.getTokenInfo(): Promise

// Context7 integration
await manager.getDocumentation(operation: string, context?: string): Promise
await manager.getDocumentationAsComments(operation: string, context?: string): Promise
manager.enableContext7(): void
manager.disableContext7(): void
manager.clearContext7Cache(): void
manager.getContext7Stats(): { size: number; keys: string[] }

类型

interface EmailComposition {
  to: string[];
  cc?: string[];
  bcc?: string[];
  subject: string;
  body: string;
  isHtml?: boolean;
  attachments?: EmailAttachment[];
}

interface EmailListOptions {
  query?: string;
  labelIds?: string[];
  maxResults?: number;
  pageToken?: string;
  includeSpamTrash?: boolean;
  userId?: string;
}

interface BatchOperation {
  messageIds: string[];
  action: 'read' | 'unread' | 'archive' | 'delete' | 'trash' | 'spam';
  labelIds?: string[];
}

🔍 高级功能

搜索查询

Gmail MCP支持高级搜索查询：

// Search examples
await manager.listMessages({ query: 'is:unread' });
await manager.listMessages({ query: 'from:important@company.com' });
await manager.listMessages({ query: 'has:attachment subject:invoice' });
await manager.listMessages({ query: 'is:starred newer_than:7d' });
await manager.listMessages({ query: 'label:important OR label:urgent' });

批量操作

高效处理多条消息：

const operation = {
  messageIds: ['msg1', 'msg2', 'msg3'],
  action: 'archive'
};

await manager.performBatchOperation(operation);

带附件的HTML电子邮件

const email = {
  to: ['recipient@example.com'],
  subject: 'Report with Attachment',
  body: '
Monthly Report

Please find the report attached.
',
  isHtml: true,
  attachments: [
    {
      filename: 'report.pdf',
      content: fileBuffer, // Buffer or base64 string
      contentType: 'application/pdf'
    }
  ]
};

await manager.sendMessage(email);

🛠️ 发展

从源头构建

# Clone the repository
git clone https://github.com/Simplify-Technology/gmail-mcp-manager.git
cd gmail-mcp-manager

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Start development mode
npm run dev

项目结构

src/
├── auth.service.ts      # OAuth2 authentication
├── gmail.service.ts     # Gmail API operations
├── context7.ts          # Context7 integration
├── index.ts             # Main module exports
├── cli.ts               # CLI interface
└── types.ts             # TypeScript definitions

examples/
├── basic-usage.js       # Basic usage example
└── advanced-usage.js    # Advanced features example

🔒 安全

• 令牌存储：令牌存储在 600 权限（仅限所有者读/写）
• 环境变量：从不承诺 .env 文件到版本控制
• 范围：使用用例所需的最小范围
• 超文本传输安全协议：在生产环境中始终使用HTTPS重定向URI

🤝 贡献

1. 分叉存储库
2. 创建要素分支： git checkout -b feature/amazing-feature
3. 提交您的更改： git commit -m 'Add amazing feature'
4. 推到分支： git push origin feature/amazing-feature
5. 打开拉取请求

📄 许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

• 谷歌认证库
• 上下文7 MCP
• 指挥官.js

📞 支持

• 📖 文档
• 🐛 问题追踪
• 💬 讨论

______________________________________________________________________

由以下材料制成❤️ 对于MCP生态系统