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
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Gmail MCP Serverlist my unread emails from the last 2 days"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Enhanced Gmail MCP Server
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
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.