GmailMcp
MCP server for gmail
Ask AI about GmailMcp
Powered by Claude Β· Grounded in docs
I know everything about GmailMcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
π§ Gmail MCP Server
Dual-mode Gmail integration: Direct CLI operations + MCP server for AI assistants
Overview
Gmail MCP Server is a versatile .NET global tool that bridges your Gmail account with both human users and AI assistants. It provides two distinct modes of operation:
CLI Mode - Direct command-line interface for searching messages, reading emails, and downloading attachments using familiar terminal commands.
MCP Mode - Model Context Protocol server that enables AI assistants (like Claude) to interact with your Gmail account through a standardized protocol.
What Problems It Solves
- AI Email Integration: Give AI assistants secure, controlled access to your Gmail without sharing passwords
- Terminal Email Access: Quickly search and read emails from the command line for scripting and automation
- OAuth2 Security: Browser-based authentication flow with local credential storage
- Cross-Platform: Works on Windows, macOS, and Linux with .NET runtime
β¨ Features
- π Dual-mode architecture - Switch between CLI and MCP server modes seamlessly
- π OAuth2 auto-authentication - Secure browser-based authentication with automatic token refresh
- π§ Gmail operations - Search messages with Gmail query syntax, read full email content, download attachments
- π€ MCP integration - Standardized protocol for AI assistants (Claude Desktop, Cline, etc.)
- π¦ Easy installation - Available as .NET global tool via NuGet
- π Advanced search - Full Gmail query syntax support (from:, subject:, is:unread, etc.)
- π» Script-friendly - JSON output mode for automation and integration
- π Cross-platform - Runs anywhere .NET 8.0 or 10.0 is supported
π Quick Start
# Install the global tool
dotnet tool install -g GmailMcp
# Authenticate with your Gmail account
dotnet-gmail auth
# Search for messages (CLI mode)
dotnet-gmail search "from:example@gmail.com"
# Read a specific message
dotnet-gmail read <message-id>
# Start MCP server for AI assistants
dotnet-gmail mcp
π¦ Installation
Prerequisites
- .NET 8.0 or 10.0 SDK - Download here
- Google Cloud Console account - Required for OAuth2 credentials
- Gmail account - The account you want to access
Step 1: Google Cloud Console Setup
- Go to Google Cloud Console
- Create a new project or select an existing one
- Enable the Gmail API for your project
- Navigate to Credentials > Create Credentials > OAuth 2.0 Client ID
- Choose Desktop app as the application type
- Download the credentials JSON file
- Rename it to
gcp-oauth.keys.json - Place it in
~/.gmail-mcp/(create the directory if needed)
File location:
- Windows:
%USERPROFILE%\.gmail-mcp\gcp-oauth.keys.json - macOS/Linux:
~/.gmail-mcp/gcp-oauth.keys.json
Step 2: Install the Tool
dotnet tool install -g GmailMcp
Step 3: Authenticate
dotnet-gmail auth
This will:
- Open your default browser
- Prompt you to sign in to Google
- Request permission to access your Gmail
- Save the OAuth2 tokens locally in
~/.gmail-mcp/token.json
π§ Usage
CLI Mode
Authentication
# Authenticate and store credentials
dotnet-gmail auth
Search Messages
# Basic search
dotnet-gmail search "from:john@example.com"
# Search with subject
dotnet-gmail search "subject:invoice"
# Complex query
dotnet-gmail search "from:support@company.com is:unread after:2024/01/01"
# Limit results (default: 10)
dotnet-gmail search "from:boss@company.com" --max-results 5
# JSON output for scripting
dotnet-gmail search "is:unread" --robot
Common search operators:
from:user@example.com- Emails from specific senderto:user@example.com- Emails to specific recipientsubject:keyword- Subject contains keywordis:unread- Unread messages onlyhas:attachment- Messages with attachmentsafter:2024/01/01- Messages after datebefore:2024/12/31- Messages before date
Read Message
# Read message by ID (get ID from search results)
dotnet-gmail read 18d4f2a3b5c6e7f8
# JSON output
dotnet-gmail read 18d4f2a3b5c6e7f8 --robot
Download Attachment
# Download to current directory
dotnet-gmail download <message-id> <attachment-id>
# Download to specific directory
dotnet-gmail download <message-id> <attachment-id> --output ./downloads
# Custom filename
dotnet-gmail download <message-id> <attachment-id> --filename report.pdf
MCP Mode
Quick MCP Setup
Add the following to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"gmail": {
"command": "dotnet-gmail",
"args": ["mcp"]
}
}
}
Restart Claude Desktop after making changes.
For detailed MCP configuration instructions, troubleshooting, and advanced setup options, see the MCP Configuration Guide.
Available MCP Tools
Once configured, Claude can use these tools:
| Tool | Parameters | Description |
|---|---|---|
search_messages | query, maxResults | Search Gmail using query syntax, returns message metadata |
read_message | messageId | Read full message content including body and attachments |
download_attachment | messageId, attachmentId, outputDirectory, filename | Download specific attachment to disk |
Example Claude prompts:
- "Search my Gmail for unread messages from support@example.com"
- "Read the message with ID 18d4f2a3b5c6e7f8"
- "Download the PDF attachment from that email"
- "Find all emails from my boss in the last week with attachments"
ποΈ Architecture
βββββββββββββββββββββββββββββββββββββββββββββββββββ
β Gmail MCP Server β
β β
β ββββββββββββββββ βββββββββββββββββββ β
β β CLI Mode β β MCP Mode β β
β β β β β β
β β β’ auth β β β’ stdio server β β
β β β’ search β β β’ tool calls β β
β β β’ read β β β’ JSON-RPC β β
β β β’ download β β β β
β ββββββββ¬ββββββββ ββββββββββ¬βββββββββ β
β β β β
β ββββββββββββ¬ββββββββββββββββ β
β β β
β ββββββββββββΌβββββββββββ β
β β Shared Services β β
β β β β
β β β’ AuthService β β
β β β’ GmailService β β
β ββββββββββββ¬βββββββββββ β
β β β
β ββββββββββββΌβββββββββββ β
β β Gmail API v1 β β
β β (Google.Apis) β β
β βββββββββββββββββββββββ β
βββββββββββββββββββββββββββββββββββββββββββββββββββ
Key Components:
- Program.cs - Entry point with dependency injection setup
- Commands - CLI command implementations (auth, search, read, download)
- Services - Shared business logic (authentication, Gmail operations)
- MCP Server - Model Context Protocol server and tool definitions
- Models - Data structures for messages and attachments
π Authentication & Security
OAuth2 Flow
Gmail MCP Server uses OAuth2 for secure authentication:
- Client credentials (
gcp-oauth.keys.json) stored in~/.gmail-mcp/ - User consent obtained through browser-based Google login
- Access tokens stored locally in
~/.gmail-mcp/token.json - Automatic refresh when tokens expire
Security Best Practices
- Never commit
gcp-oauth.keys.jsonortoken.jsonto version control - Restrict OAuth scopes to minimum required (currently uses
GmailReadonlyScope) - Review granted permissions in Google Account settings
- Rotate credentials if you suspect compromise
Setting Up Google Cloud Credentials
Detailed Steps:
-
Navigate to Google Cloud Console
-
Create a new project:
- Click "Select a project" > "New Project"
- Name it (e.g., "Gmail MCP Access")
- Click "Create"
-
Enable Gmail API:
- Go to "APIs & Services" > "Library"
- Search for "Gmail API"
- Click "Enable"
-
Create OAuth 2.0 credentials:
- Go to "APIs & Services" > "Credentials"
- Click "+ CREATE CREDENTIALS" > "OAuth client ID"
- If prompted, configure the OAuth consent screen:
- User Type: "External"
- App name: "Gmail MCP Server"
- User support email: your email
- Developer contact: your email
- Save and continue through remaining steps
- Application type: "Desktop app"
- Name: "Gmail MCP Desktop"
- Click "Create"
-
Download credentials:
- Click the download icon (β¬) next to your newly created OAuth client
- Save as
gcp-oauth.keys.json - Move to
~/.gmail-mcp/gcp-oauth.keys.json
-
First authentication:
dotnet-gmail auth- Browser opens automatically
- Sign in with your Google account
- Grant requested permissions
- Token saved to
~/.gmail-mcp/token.json
π οΈ Development
Clone & Build
# Clone repository
git clone https://github.com/yourusername/dotnet-gmail-mcp.git
cd dotnet-gmail-mcp
# Build solution
dotnet build
# Run locally
dotnet run --project src/GmailMcp
Local Testing
Test CLI Commands
# Build and install locally
dotnet pack src/GmailMcp
dotnet tool install -g --add-source ./src/GmailMcp/nupkg GmailMcp
# Test authentication
dotnet-gmail auth
# Test search
dotnet-gmail search "is:unread" --max-results 5
# Test read
dotnet-gmail read <message-id>
# Uninstall when done
dotnet tool uninstall -g GmailMcp
Test MCP Integration
# Start MCP server in one terminal
dotnet-gmail mcp
# In another terminal, send MCP protocol messages via stdin
# (or configure Claude Desktop to use local build)
Project Structure
dotnet-gmail-mcp/
βββ src/
β βββ GmailMcp/
β βββ Commands/ # CLI command implementations
β β βββ AuthCommand.cs
β β βββ SearchCommand.cs
β β βββ ReadCommand.cs
β β βββ DownloadCommand.cs
β β βββ McpCommand.cs
β βββ Services/ # Business logic layer
β β βββ IAuthenticationService.cs
β β βββ AuthenticationService.cs
β β βββ IGmailService.cs
β β βββ GmailService.cs
β βββ Models/ # Data structures
β β βββ GmailMessage.cs
β β βββ GmailAttachment.cs
β βββ Mcp/ # MCP server and tools
β β βββ GmailMcpServer.cs
β β βββ Tools/
β β βββ SearchMessagesTool.cs
β β βββ ReadMessageTool.cs
β β βββ DownloadAttachmentTool.cs
β βββ Program.cs # Entry point and DI setup
β βββ GmailMcp.csproj # Project configuration
βββ README.md
π MCP Tools Reference
search_messages
Search Gmail messages using Gmail query syntax.
Parameters:
query(string, required) - Gmail search query (e.g., "from:user@example.com", "subject:meeting", "is:unread")maxResults(int, optional) - Maximum number of results to return (default: 10, max: 100)
Returns: JSON array of message objects with:
id- Message IDthreadId- Thread IDsubject- Email subjectfrom- Sender email addressto- Array of recipient email addressesdate- ISO 8601 formatted datehasAttachments- Boolean indicating if attachments existattachmentCount- Number of attachments
Example:
{
"query": "from:boss@company.com is:unread",
"maxResults": 5
}
read_message
Read full content of a specific Gmail message.
Parameters:
messageId(string, required) - Unique message identifier from search results
Returns: JSON object with:
id- Message IDthreadId- Thread IDsubject- Email subjectfrom- Sender email addressto- Array of recipient email addressesdate- ISO 8601 formatted datebody- Plain text email bodyattachments- Array of attachment objects withid,filename,mimeType,size
Example:
{
"messageId": "18d4f2a3b5c6e7f8"
}
download_attachment
Download an attachment from a Gmail message to local disk.
Parameters:
messageId(string, required) - Message containing the attachmentattachmentId(string, required) - Attachment identifier from messageoutputDirectory(string, optional) - Directory to save file (default: current directory)filename(string, optional) - Custom filename (default: original filename)
Returns: JSON object with:
filePath- Full path to downloaded filefilename- Name of the saved filesize- File size in bytes
Example:
{
"messageId": "18d4f2a3b5c6e7f8",
"attachmentId": "ANGjdJ8wK...",
"outputDirectory": "./downloads",
"filename": "report.pdf"
}
π€ Contributing
Contributions are welcome! Please feel free to submit issues, fork the repository, and create pull requests.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature) - Commit your changes (
git commit -m 'Add amazing feature') - Push to the branch (
git push origin feature/amazing-feature) - Open a Pull Request
π License
This project is licensed under the MIT License. See LICENSE file for details.
π Related Projects
- Model Context Protocol - MCP specification and SDKs
- Claude Desktop - AI assistant with MCP support
- Google APIs .NET - Gmail API client library
Built with β€οΈ using .NET and Model Context Protocol
