AI导哈

Gmail API集成服务器

一个用于Gmail API集成的模型上下文协议（MCP）服务器实现，使AI助手能够与Gmail服务交互，支持电子邮件操作、草稿管理和日历事件处理。

  • by zacco16
  • TypeScript
  • 本地部署
  • 2 星标
  • 更新于
在 GitHub 查看 zacco16/gmail-mcp-server

使用说明

Gmail MCP服务器

用于Gmail API集成的模型上下文协议（MCP）服务器实现，使人工智能助手能够与Gmail服务交互。

特性

核心功能

  • 电子邮件操作
    • 列出具有高级过滤功能的电子邮件
    • 阅读内容完整的特定电子邮件
    • 创建和发送新电子邮件
  • 草案管理
    • 创建新草稿
    • 列出现有草稿
    • 阅读草稿内容
    • 更新草稿内容和收件人
    • 删除草稿
  • 日历操作
    • 列出即将到来的日历事件
    • 阅读详细的事件信息
    • 创建新的日历事件
    • 事件过滤和搜索
    • 时区支持
    • iOS日历同步支持

搜索和筛选

  • Gmail搜索查询支持
  • 基于标签的过滤
  • 可定制的结果限制
  • 日历事件搜索功能

安全

  • Google OAuth2.0集成
  • 安全的凭证管理
  • 刷新令牌处理
  • 多范围授权支持

快速开始

先决条件

  • Node.js（v14或更高版本）
  • npm（v6或更高版本）
  • 启用Gmail和日历API的谷歌云平台帐户
  • 具有适当作用域的OAuth 2.0凭据

安装

  1. 克隆和安装依赖关系：

    git clone [repository-url]
cd gmail-mcp-server
npm install

  2. 配置环境：

    # Create .env file
cp .env.example .env

# Add your credentials:
GOOGLE_CLIENT_ID="your_client_id"
GOOGLE_CLIENT_SECRET="your_client_secret"
REDIRECT_URI="http://localhost:4100/code"
GOOGLE_REFRESH_TOKEN="your_refresh_token"

  3. 构建并运行：

    npm run build
npm start

发展

可用脚本

  • npm run dev -使用手表模式构建和运行
  • npm run build -构建项目
  • npm run clean -清理构建工件
  • npm run watch -注意变化

项目结构

gmail-mcp-server/
├── src/
│   ├── config/         # Configuration and setup
│   ├── services/       # Core business logic
│   │   ├── gmail/      # Gmail services
│   │   └── calendar/   # Calendar services
│   ├── tools/          # MCP tool implementations
│   │   ├── calendar/   # Calendar tools
│   │   ├── drafts/     # Draft management tools
│   │   └── messages/   # Email tools
│   ├── types/          # TypeScript definitions
│   └── index.ts        # Server entry point
├── dist/              # Compiled JavaScript
└── tests/             # Test files (pending)

API接口

列出邮件

listEmails({
  maxResults?: number,    // Default: 10
  query?: string,         // Gmail search query
  labelIds?: string[],    // Filter by labels
  verbose?: boolean       // Include details
})

读取消息

readEmail({
  messageId: string    // Message ID to fetch
})

草稿操作

// List Drafts
listDrafts({
  maxResults?: number,    // Default: 10
  query?: string,         // Search query
  verbose?: boolean       // Include details
})

// Read Draft
readDraft({
  draftId: string        // Draft ID to fetch
})

// Create Draft
draftEmail({
  to: string[],
  subject: string,
  body: string,
  cc?: string[],
  bcc?: string[],
  isHtml?: boolean
})

// Update Draft
updateDraft({
  draftId: string,       // Draft ID to update
  to?: string[],         // New recipients
  cc?: string[],         // New CC recipients
  bcc?: string[],         // New BCC recipients
  subject?: string,      // New subject
  body?: string,         // New body content
  isHtml?: boolean       // Content type flag
})

// Delete Draft
deleteDraft({
  draftId: string        // Draft ID to delete
})

发送电子邮件

sendEmail({
  to: string[],
  subject: string,
  body: string,
  cc?: string[],
  bcc?: string[],
  isHtml?: boolean,
  draftId?: string    // Optional: send existing draft
})

日历操作

// List Events
listEvents({
  maxResults?: number,    // Default: 25
  timeMin?: string,       // Start time (ISO 8601)
  timeMax?: string,       // End time (ISO 8601)
  query?: string,         // Text search term
  timeZone?: string      // Default: Australia/Brisbane
})

// Read Event Details
readEvent({
  eventId: string,       // Event ID to fetch details
  timeZone?: string     // Default: Australia/Brisbane
})

// Create Event
createEvent({
  summary: string,       // Event title
  start: {
    dateTime: string,    // ISO 8601 start time
    timeZone?: string    // Start time timezone
  },
  end: {
    dateTime: string,    // ISO 8601 end time
    timeZone?: string    // End time timezone
  },
  description?: string,  // Optional event description
  location?: string,     // Optional event location
  attendees?: Array<{    // Optional attendees
    email: string,
    displayName?: string,
    optional?: boolean
  }>,
  status?: 'confirmed' | 'tentative' | 'cancelled',
  sendNotifications?: boolean
})

错误处理

服务器为以下对象实现了全面的错误处理：

  • 身份验证失败
  • API费率限制
  • 无效请求
  • 网络问题
  • 日历同步问题
  • 事件ID验证
  • 时区验证

贡献

请看 贡献.md 作为指导方针。

更新日志

看 更改日志.md 查看版本历史和更新。

路线图

看 Backlog.md 计划中的功能和改进。

许可证

MIT许可证-请参阅 许可证 了解详情。

相关 MCP