https://github.com/cafferychen777/gmail-mcp

Gmail automation via a Chrome extension + Model Context Protocol (MCP). Control Gmail from Claude Desktop. No API keys. Free.

https://github.com/cafferychen777/gmail-mcp

Keywords

Repository

Gmail automation via a Chrome extension + Model Context Protocol (MCP). Control Gmail from Claude Desktop. No API keys. Free.

https://github.com/cafferychen777/gmail-mcp/blob/main/

# Gmail MCP Bridge

English | [ README.zh-CN.md](./README.zh-CN.md)

> Control Gmail from Claude. No Google Cloud. No OAuth. No API keys.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Chrome Extension](https://img.shields.io/badge/Chrome-Extension-blue.svg)](https://developer.chrome.com/docs/extensions/)
[![MCP Compatible](https://img.shields.io/badge/MCP-Compatible-green.svg)](https://modelcontextprotocol.io/)
[![Status: Production Ready](https://img.shields.io/badge/Status-Production%20Ready-brightgreen.svg)](https://github.com/cafferychen777/gmail-mcp)
![GitHub Repo stars](https://img.shields.io/github/stars/cafferychen777/gmail-mcp?style=social)
[![Website](https://img.shields.io/website?url=https%3A%2F%2Fcafferychen777.github.io%2Fgmail-mcp%2F)](https://cafferychen777.github.io/gmail-mcp/)
[![GitHub release (latest SemVer)](https://img.shields.io/github/v/release/cafferychen777/gmail-mcp?sort=semver)](https://github.com/cafferychen777/gmail-mcp/releases)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
[![Discussions](https://img.shields.io/github/discussions/cafferychen777/gmail-mcp)](https://github.com/cafferychen777/gmail-mcp/discussions)
[![CodeQL](https://github.com/cafferychen777/gmail-mcp/actions/workflows/codeql.yml/badge.svg)](https://github.com/cafferychen777/gmail-mcp/actions/workflows/codeql.yml)
[![Contributors](https://img.shields.io/github/contributors/cafferychen777/gmail-mcp)](https://github.com/cafferychen777/gmail-mcp/graphs/contributors)
[![Good first issues](https://img.shields.io/github/issues-search?query=repo%3Acafferychen777%2Fgmail-mcp%20label%3A%22good-first-issue%22%20state%3Aopen&label=good%20first%20issues)](https://github.com/cafferychen777/gmail-mcp/labels/good-first-issue)
[![Open issues](https://img.shields.io/github/issues/cafferychen777/gmail-mcp)](https://github.com/cafferychen777/gmail-mcp/issues)
[![Open PRs](https://img.shields.io/github/issues-pr/cafferychen777/gmail-mcp)](https://github.com/cafferychen777/gmail-mcp/pulls)
[![No Google Cloud / OAuth](https://img.shields.io/badge/No%20Google%20Cloud%20%2F%20OAuth-Yes-ff69b4)](#why-no-google-cloud)

Enable Gmail automation for AI assistants through a Chrome extension and the Model Context Protocol. Works locally, respects your browser session, and requires no Google API keys.

If this project helps you, please  star the repo and join the [Discussions](https://github.com/cafferychen777/gmail-mcp/discussions).

>  Bold advantage: No Google Cloud project. No OAuth consent screen. No API keys. It uses your existing Chrome session to act in Gmail.

## Why no Google Cloud

This project works locally by leveraging your existing Chrome browser session. The extension and MCP server act on Gmail the same way you do in the browser, so you do not need to set up a Google Cloud project, OAuth consent screen, or any API keys.

Benefits:
- Simpler onboarding: no cloud console, no OAuth app review.
- Privacy: actions stay within your local browser session.
- Portability: works anywhere Chrome runs.

Limitations to note:
- Requires Chrome to be installed and signed in to the target Gmail account.
- Actions follow the permissions of your current Gmail session.

##  Installation

For a guided setup, see the Quick Start and Website:
- Quick Start: [docs/quick-start/installation.md](./docs/quick-start/installation.md)
- Website: https://cafferychen777.github.io/gmail-mcp/

Prerequisites:
- Node.js 18+
- Google Chrome (latest)
- Claude Desktop (with MCP enabled)

```bash
# One-command install (recommended)
./bin/gmail-mcp install

# Or manual setup
cd gmail-mcp-extension/mcp-server && npm install
```

##  Project Structure

```
gmail-mcp/
 bin/                     # CLI utilities (installer/manager)
    gmail-mcp
 gmail-mcp-extension/     # Chrome Extension + MCP bridge server
    extension/           # Chrome extension source
    mcp-server/          # MCP bridge server
    src/                 # Core logic and recovery system
 docs/                    # Documentation
    planning/
    reports/
    analysis/
 scripts/                 # Tooling scripts
    test/
    util/
 src/                     # Advanced features
    core/
    plugins/
 tests/
 tools/
 Key docs
     README.md
     README.zh-CN.md
     CLAUDE.md
     CONTRIBUTING.md
     RELEASE.md
```

##  Features

- Gmail read/search/send/reply
- Full Gmail search syntax support
- Multi-account switching
- Auto-recovery (95%+ common failures)
- Self-diagnosis and repair utilities
- Low-latency, high-throughput local bridge

##  Usage

### CLI management

```bash
gmail-mcp status    # Check system status
gmail-mcp doctor    # Diagnose issues
gmail-mcp fix       # Auto-fix common problems
gmail-mcp test      # Run tests
```

### In Claude Desktop

After installation, just ask Claude:
- "Check my latest emails"
- "Send an email to john@example.com"
- "Search emails containing 'project'"

##  Documentation

- Developer architecture: [docs/developer/architecture.md](docs/developer/architecture.md)
- Roadmap: [docs/planning/COMPREHENSIVE_IMPROVEMENT_ROADMAP.md](docs/planning/COMPREHENSIVE_IMPROVEMENT_ROADMAP.md)
- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)

##  Demo / Screenshots

Below are placeholder screenshots; a short demo GIF will be added soon.

![Install](docs/assets/screenshots/install.svg)

![Claude command triggering Gmail tools](docs/assets/screenshots/claude-command.svg)

![Gmail action executed](docs/assets/screenshots/gmail-action.svg)

Planned: `docs/assets/screenshots/demo.gif` (10s).

If you'd like to help, check the good first issues.

##  Why this project

- No API keys, works directly with your browser session
- Fast local bridge with MCP for AI assistants
- Production-ready structure with installer and diagnostics

##  Social preview (Open Graph)

Improve link previews when sharing the repo by uploading a social image:

1. Use the placeholder at `docs/assets/images/og-preview.svg` (export to 1200630 PNG if needed)
2. Go to GitHub  Repository Settings  General  Social preview  Upload the image

##  Contributing

PRs welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md).

##  License

MIT License  see [LICENSE](LICENSE)

---

Gmail MCP Bridge  Control Gmail from Claude Desktop via MCP 

##  Community & Support

- Code of Conduct: [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
- Security policy: [SECURITY.md](SECURITY.md)
- Support: [SUPPORT.md](SUPPORT.md)
- Discussions: https://github.com/cafferychen777/gmail-mcp/discussions
- Good first issues: https://github.com/cafferychen777/gmail-mcp/labels/good-first-issue
- Help wanted: https://github.com/cafferychen777/gmail-mcp/labels/help-wanted

Owner

GitHub Events

Committers

Last synced: 7 months ago