
Local MCP server for Gmail — send/search/label with your data staying between your machine and
Local MCP server for Gmail — send/search/label with your data staying between your machine and Google
·
Local Gmail MCP server. Your emails never leave your machine except to Google. No third party in the middle.
Most Gmail integrations for AI assistants — including the "official" MCP connectors — route your emails through a third-party server before they reach the AI. That means the third party sees plaintext of every message you search, read, or send.
This project takes a different path: it runs on your machine, authenticates directly to Google Gmail API with your OAuth credentials, and exposes 6 tools to your local AI client (Claude Code, Claude Desktop, or any MCP-compatible client) over stdio.
Data flow: You ↔ this server (on your machine) ↔ Google Gmail API. That's the whole path. No hosted service. No proxy. No third-party access to your inbox.
You can read the entire server — one file, a few hundred lines of Python — and confirm for yourself.
Six tools exposed over MCP:
search_messages — Gmail search syntax (e.g. from:foo@bar is:unread newer_than:7d)get_message — full headers + decoded text/plain bodysend_message — with optional local file attachments (this is a feature the official connector lacks), and proper in-thread replies via reply_to_message_id (sets In-Reply-To/References and Gmail threadId; to/subject default to the original sender and Re: <subject>)create_draft — same fields as send (including replies), does not sendlist_labels — all labels with idsmodify_labels — add/remove labels on a messagegit clone https://github.com/bartosz-kuc/honest-gmail-mcp.git
cd honest-gmail-mcppython3 -m venv venv
./venv/bin/pip install -r requirements.txtOn Windows, create the venv with py -m venv venv and use venv\Scripts\pip / venv\Scripts\python in place of the venv/bin/... paths shown throughout this README.
You create your own OAuth client in your own Google Cloud project. Nobody but you controls it.
honest-gmail-mcp)honest-gmail-mcpcredentials.json in this repo's root directory./venv/bin/python authorize.pyA browser tab will open. Sign in, click Allow. The refresh token is saved locally as token.json and the script exits.
If you skip this step, the server runs the same browser flow on its first tool call. (server.py itself is meant to be launched by an MCP client; started by hand it just waits silently on stdio.)
Claude Code:
claude mcp add gmail-personal /absolute/path/to/venv/bin/python /absolute/path/to/server.pyClaude Desktop: edit claude_desktop_config.json (find via Claude menu → Settings → Developer → Edit Config):
{
"mcpServers": {
"gmail-personal": {
"command": "/absolute/path/to/venv/bin/python",
"args": ["/absolute/path/to/server.py"]
}
}
}Restart the client. Tools appear as mcp__gmail-personal__search_messages etc.
One server instance serves one account. For more accounts, register one instance per account (same checkout), each with its own token file, via environment variables:
| Variable | Default | Purpose |
|---|---|---|
GMAIL_TOKEN_PATH | token.json next to server.py | Refresh token of the account this instance uses |
GMAIL_CREDENTIALS_PATH | credentials.json next to server.py | OAuth client JSON; can be shared by all accounts |
GMAIL_SERVER_NAME | gmail-personal | Server name the instance reports to the MCP client |
Paths are used as given (no ~ expansion), so use absolute paths.
Add the extra address as a test user on the OAuth consent screen (step 3).
Mint its token. A relative file name is saved next to authorize.py; the optional email pre-selects the account at Google sign-in:
./venv/bin/python authorize.py token.work.json [email protected]Register a second server that points at it, as another entry under mcpServers (Claude Desktop config shown; the same entry works in Claude Code's .mcp.json):
"gmail-work": {
"command": "/absolute/path/to/venv/bin/python",
"args": ["/absolute/path/to/server.py"],
"env": {
"GMAIL_TOKEN_PATH": "/absolute/path/to/token.work.json",
"GMAIL_SERVER_NAME": "gmail-work"
}
}.gitignore covers token*.json, so per-account token files are not committed.
pip / uvx)The package contains only the server module (command honest-gmail-mcp); authorize.py is not included. Default credentials.json/token.json paths resolve next to the installed module (site-packages or uv's cache), which is no place for secrets and can be wiped on upgrade. Set both variables to absolute paths in an existing directory you own:
"gmail-personal": {
"command": "uvx",
"args": ["honest-gmail-mcp"],
"env": {
"GMAIL_CREDENTIALS_PATH": "/absolute/path/to/credentials.json",
"GMAIL_TOKEN_PATH": "/absolute/path/to/token.json"
}
}If the token file does not exist yet, the server opens the browser consent flow on its first tool call and writes the token to GMAIL_TOKEN_PATH.
These variables and the mcp 2.x API need version 0.2.0 or newer; 0.1.0 does not read them and fails to start with mcp 2.x.
Your AI client (Claude Code / Claude Desktop)
↕ MCP protocol over stdio (local process pipe)
This server (Python, on your machine)
↕ HTTPS to googleapis.com
Google Gmail APINo cloud in the middle. No telemetry. No analytics. The server has no network dependencies beyond Google itself.
The credentials.json (your OAuth client secret) and token.json (your refresh token) stay on your disk. Both are .gitignored so a stray git push cannot leak them.
gmail.modify — covers read, labels, send, drafts. It does not cover Gmail settings, filters, delegates, or account management..gitignore blocks credentials.json, token.json, and virtualenvs.server.py is a few hundred lines. Read it once and you know exactly what it can and cannot do.Bartosz Kuć — Warsaw-based developer, JDG owner running skanfirmy.pl.
Site: https://skanfirmy.pl
GitHub: https://github.com/bartosz-kuc
Email: [email protected]
Available for consulting on Polish tax and business integrations (KSeF, GUS/NFZ/GIOŚ APIs, mBank data), MCP server design, and AI-assisted tooling for JDGs and small teams. See skanfirmy.pl/uslugi for productized packages (audit 3k PLN, setup 8-15k PLN, retainer 2-4k PLN/mo), or reach out via email.
MIT — see LICENSE.
Issues and PRs welcome. Please keep the code minimal and auditable — the whole selling point is that a user can read it in one sitting.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add gmail-personal -- /absolute/path/to/venv/bin/python /absolute/path/to/server.py{
"mcpServers": {
"gmail-personal": {
"args": [
"/absolute/path/to/server.py"
],
"command": "/absolute/path/to/venv/bin/python"
}
}
}code --add-mcp '{"name":"gmail-personal","args":["/absolute/path/to/server.py"],"command":"/absolute/path/to/venv/bin/python"}'[mcp_servers.gmail-personal]
command = "/absolute/path/to/venv/bin/python"
args = ["/absolute/path/to/server.py"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/honest-gmail-mcp to learn what the "Honest Gmail Mcp" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
claude mcp add gmail-personal /absolute/path/to/venv/bin/python /absolute/path/to/server.pyThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/honest-gmail-mcp)Nothing comparable is listed yet.
No tagged releases on record.
Connect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "honest-gmail-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.