A
security-
licenseA
qualityA Model Context Protocol server that provides tools for interacting with Gmail and Calendar APIs, enabling programmatic management of emails and calendar events.
Last updated -
8
25
MIT License
Enables comprehensive email operations including listing, reading, and sending emails, as well as draft management with creation, reading, updating, and deletion capabilities
Provides calendar functionality for listing, reading, and creating events with support for filtering, timezone handling, and attendee management
Supports calendar synchronization with iOS devices, allowing events created or modified through the MCP to appear on Apple mobile devices
Gmail MCP Server
A Model Context Protocol (MCP) server implementation for Gmail API integration, enabling AI assistants to interact with Gmail services.
Features
Core Functionality
Email Operations
List emails with advanced filtering
Read specific emails with full content
Create and send new emails
Draft Management
Create new drafts
List existing drafts
Read draft content
Update draft content and recipients
Delete drafts
Calendar Operations
List upcoming calendar events
Read detailed event information
Create new calendar events
Event filtering and search
Timezone support
iOS calendar sync support
Search & Filtering
Gmail search query support
Label-based filtering
Customizable result limits
Calendar event search capabilities
Security
Google OAuth2.0 integration
Secure credential management
Refresh token handling
Multi-scope authorization support
Quick Start
Prerequisites
Node.js (v14 or higher)
npm (v6 or higher)
Google Cloud Platform account with Gmail and Calendar APIs enabled
OAuth 2.0 credentials with appropriate scopes
Installation
Clone and install dependencies:
git clone [repository-url] cd gmail-mcp-server npm installConfigure environment:
# 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"Build and run:
npm run build npm start
Development
Available Scripts
npm run dev- Build and run with watch modenpm run build- Build the projectnpm run clean- Clean build artifactsnpm run watch- Watch for changes
Project Structure
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 Interface
List Messages
listEmails({
maxResults?: number, // Default: 10
query?: string, // Gmail search query
labelIds?: string[], // Filter by labels
verbose?: boolean // Include details
})
Read Message
readEmail({
messageId: string // Message ID to fetch
})
Draft Operations
// 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
})
Send Email
sendEmail({
to: string[],
subject: string,
body: string,
cc?: string[],
bcc?: string[],
isHtml?: boolean,
draftId?: string // Optional: send existing draft
})
Calendar Operations
// 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
})
Error Handling
The server implements comprehensive error handling for:
Authentication failures
API rate limits
Invalid requests
Network issues
Calendar sync issues
Event ID validation
Timezone validation
Contributing
Please see CONTRIBUTING.md for guidelines.
Changelog
See CHANGELOG.md for version history and updates.
Roadmap
See Backlog.md for planned features and improvements.
License
MIT License - see LICENSE for details.
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
A Model Context Protocol server that enables AI assistants to interact with Gmail services, supporting email operations, draft management, and calendar functionality through Google API integration.
Related Resources
Related MCP Servers
- -security-license-qualityA Model Context Protocol server that enables AI assistants like Claude to interact with Gmail through natural language, providing comprehensive email management capabilities including sending, reading, organizing, searching, and managing drafts and labels.Last updated -7GPL 3.0
- Asecurity-licenseAqualityA Model Context Protocol server that provides an interface for AI models to interact with Google Docs, enabling reading, creating, updating, and searching Google Documents.Last updated -43
- -security-license-qualityA Model Context Protocol server that enables AI assistants to manage Gmail through natural language interactions with features like sending emails, searching, and label management.Last updated -2,386MIT License