📧 Gmail MCP Server

A powerful Gmail MCP server for AI agents — search, read, send, and organize emails via Claude Desktop, Claude Code, Cursor, and more.

⭐ If you find this project useful, please consider giving it a star on GitHub! It helps others discover it. ⭐

---

⚡ Quick Start

# One-command setup — auto-configures your AI client
npx gmail-mcp-server setup

That's it. The setup wizard will:

1. Check your Google OAuth credentials
2. Let you choose your AI client (Claude Desktop, Claude Code, Cursor, Windsurf)
3. Auto-write the config file
4. Run the OAuth authentication flow

---

✨ Why choose this MCP?

While Google provides workspace integrations and generic email readers exist, this MCP is explicitly built for AI Agents acting autonomously:

• Zero-Config Setup: npx gmail-mcp-server setup detects your OS and AI client, automatically editing your local configuration JSON. No manual path mapping required.
• Built for AI Agents: Includes tools like advanced_filter (search + bulk actions with LLM-friendly dry-runs), batch_modify_emails (modify 1000 emails at once), and get_frequent_contacts (turn an inbox into a CRM context).
• 100% Local & Private: Bring-your-own-credentials. Tokens remain strictly on your machine. No proxy servers, no telemetry, and no third-party email routing.
• Modular & Extensible: Clean, deeply typed domain-driven structure (e.g., src/tools/compose.ts, src/tools/search.ts) making it extremely easy for developers to fork and extend.

---

🔧 Tools (20 tools)

Category	Tool	Description
Search	search_emails	Search with Gmail query syntax (from:, is:unread, subject:, etc.)
Read	get_email	Full email content — body, headers, attachments
	get_thread	All messages in a thread
Compose	send_email	Send a new email
	reply_email	Reply (or reply-all) keeping the thread
	forward_email	Forward with optional note
	create_draft	Save a draft (optionally in a thread)
Organize	modify_email	Add/remove labels, mark read/unread
	batch_modify_emails	Bulk modify up to 1000 emails
	trash_email	Move to trash
	untrash_email	Restore from trash
	batch_trash_emails	Bulk trash
	mark_spam	Mark as spam
	advanced_filter	Search + bulk action (archive, label, etc.) with dry-run
Labels	list_labels	List all labels with IDs
	create_label	Create new label (supports nesting)
	delete_label	Delete user-created label
Extract	extract_addresses	Extract unique addresses from search results
	format_emails	Filter, sort, reformat email data
Profile	get_profile	Your email address, message/thread counts
	get_frequent_contacts	Most-contacted addresses from sent mail
Attachments	get_attachment	Download attachment content

---

🚀 Step-by-Step Setup Guide

Follow these steps to get your Gmail MCP server running in less than 5 minutes.

1. Create Google Cloud Project & Enable API

1. Open the Google Cloud Console.
2. Create a New Project: Click the project dropdown (top left) → "New Project" → Name it Gmail MCP → "Create".
3. Enable Gmail API: Search for "Gmail API" in the search bar → Click it → Click Enable.

2. Configure OAuth Consent Screen

1. Go to APIs & Services → OAuth consent screen.
2. Select User Type: "External" (or "Internal" if you have a Google Workspace) → Click Create.
3. App Information: Fill in "App name" (e.g., Gmail MCP) and "User support email".
4. Developer Contact: Fill in your email address.
5. Click Save and Continue until you reach the Summary.
6. Add Test Users: Go back to the "OAuth consent screen" tab → Under "Test users" → Click + ADD USERS → Enter your Gmail address → Click Save.

3. Generate Credentials

1. Go to APIs & Services → Credentials.
2. Click + CREATE CREDENTIALS → Select OAuth client ID.
3. Application type: Select Desktop app.
4. Name: Give it a name (e.g., Gmail MCP Client).
5. Click Create.
6. Download JSON: In the "OAuth 2.0 Client IDs" list, click the download icon (↓) for your new client.
7. Rename & Move: Save this file as credentials.json in your project folder (or keep it ready for the setup wizard).

4. Run the Setup Wizard

Open your terminal and run:

npx gmail-mcp-server setup

The wizard will guide you through:

• Finding your credentials.json.
• Selecting your AI client (Claude, Cursor, etc.).
• Authorizing the app via your browser.

---

🖥️ Client Configuration

Claude Desktop

npx gmail-mcp-server setup   # Select "Claude Desktop"

Or manually add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "gmail-mcp-server"]
    }
  }
}

Claude Code

npx gmail-mcp-server setup   # Select "Claude Code"

Or add to ~/.claude/mcp.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "gmail-mcp-server"]
    }
  }
}

Cursor

npx gmail-mcp-server setup   # Select "Cursor"

Or add to .cursor/mcp.json:

{
  "mcpServers": {
    "gmail": {
      "command": "npx",
      "args": ["-y", "gmail-mcp-server"]
    }
  }
}

Windsurf

npx gmail-mcp-server setup   # Select "Windsurf"

---

🛠️ CLI Commands

npx gmail-mcp-server setup      # Interactive setup wizard
npx gmail-mcp-server auth       # Run OAuth flow
npx gmail-mcp-server serve      # Start MCP server (default)
npx gmail-mcp-server doctor     # Diagnose issues
npx gmail-mcp-server --help     # Show help
npx gmail-mcp-server --version  # Show version

---

🩺 Troubleshooting

If you run into issues, try the following:

1. Run the Doctor: npx gmail-mcp-server doctor will diagnose common problems with your credentials, tokens, and system.
2. Missing credentials.json: Ensure you've downloaded the file from Google Cloud Console and it's named exactly credentials.json in your current directory.
3. Invalid Grant / Expired Token: If the server can't connect, try running npx gmail-mcp-server auth to reset your OAuth tokens.
4. Port 3000 Busy: The auth flow uses port 3000. If it's busy, the flow might fail. Ensure no other apps are using port 3000 during setup.

---

💬 Usage Examples

Once configured, ask your AI agent:

• "Search my emails for unread messages from GitHub"
• "Get the full content of email ID 18abc123"
• "Show me the whole thread for this conversation"
• "Reply to that email saying thanks"
• "Forward the invoice to accounting@company.com"
• "Create a draft reply for that message"
• "Mark all newsletters from last month as read"
• "Extract all email addresses from my last 50 emails"
• "Who do I email most frequently?"
• "Download the PDF attachment from that email"

---

🔒 Security

• credentials.json — never committed (in .gitignore)
• Tokens stored in ~/.gmail-mcp/token.json — outside the project, auto-refreshed
• OAuth scope: gmail.modify (read + modify, no permanent delete or admin)
• All data stays local — no external servers, no telemetry

---

🌍 Environment Variables

Variable	Default	Description
GMAIL_CREDENTIALS_PATH	./credentials.json	Path to your OAuth credentials file
GMAIL_MCP_DIR	process.cwd()	Base directory for credentials lookup

---

🤝 Contributing

We welcome contributions! See CONTRIBUTING.md for guidelines.

git clone https://github.com/neutral-Stage/gmail-mcp-server.git
cd gmail-mcp-server
npm install
npm run build

---

📄 License

MIT — use it however you want.