AI导哈

Gmail API管理服务器

一个完整的Gmail API管理服务器，提供OAuth2认证和Context7集成，支持CLI和编程API进行邮件管理操作。

  • by Simplify-Technology
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 simplify-technology/gmail-mcp-manager

使用说明

Gmail MCP服务器

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凭据（桌面应用程序）
    • 下载凭据

  2. 配置环境

    # 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

  3. 验证

    # 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);

🔧 配置

环境变量

变量 必填 默认 描述
GOOGLE_CLIENT_ID ✅ - 谷歌OAuth2客户端ID
GOOGLE_CLIENT_SECRET ✅ - Google OAuth2客户端密码
GOOGLE_REDIRECT_URI ❌ http://localhost:3000/oauth2callback OAuth2重定向URI
GOOGLE_SCOPES ❌ gmail.modify 逗号分隔的Gmail作用域
TOKEN_STORAGE_PATH ❌ ~/.gmail-mcp-tokens.json 令牌存储文件路径
DEFAULT_USER_ID ❌ me 默认Gmail用户ID
CONTEXT7_ENABLED ❌ true 启用Context7集成

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<void>

// Message operations
await manager.listMessages(options?: EmailListOptions): Promise<ListMessagesResponse>
await manager.getMessage(messageId: string, format?: 'full' | 'metadata' | 'minimal'): Promise<GmailMessage>
await manager.sendMessage(email: EmailComposition): Promise<GmailMessage>

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

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

// Utility methods
await manager.getLabels(): Promise<ListLabelsResponse>
await manager.getEmailStats(): Promise<EmailStats>
await manager.getThread(threadId: string, format?: string): Promise<GmailThread>
await manager.listThreads(options?: EmailListOptions): Promise<ListThreadsResponse>

// Authentication
await manager.logout(): Promise<void>
await manager.getTokenInfo(): Promise<any>

// Context7 integration
await manager.getDocumentation(operation: string, context?: string): Promise<Context7Response | null>
await manager.getDocumentationAsComments(operation: string, context?: string): Promise<string>
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: '<h1>Monthly Report</h1><p>Please find the report attached.</p>',
  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许可证获得许可-请参阅 许可证 文件以获取详细信息。

🙏 致谢

📞 支持

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

相关 MCP