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 install -
Configure 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.