BedVibe Mail Bridge

A local Windows desktop app + MCP bridge that lets an AI client (Claude Code / Codex) help with your Gmail — where nothing is sent, deleted, or unsubscribed without a human button-press.

Status: v0.1.0 — local developer preview / portfolio release. Gmail only. Run-from-source. Not a consumer installer, and not clone-and-connect — see Running it yourself below.

What it is

An AI assistant can search and read your mail, propose a cleanup plan, draft replies, and map your subscriptions — but the AI can only prepare. Every action that sends, deletes, or leaves your machine happens only when you click it in the desktop app.

• Local-first. No backend, no cloud, no tunnels. The AI talks to a local stdio MCP (no port).

• Read-first & human-gated. The MCP can read and queue; it cannot Trash, Send, or unsubscribe — those live behind a GUI confirmation and are structurally unreachable from the AI side.

• Private by construction. OAuth via Google's own consent (PKCE); refresh token & desktop secret encrypted with Windows DPAPI in %APPDATA%; telemetry stores domain hashes only.

• No production credential in this repo (see Privacy below).

Related MCP server: Gmail MCP Server

Features

• Read: recent inbox, Gmail-query search, read message, list threads.

• Cleanup: AI builds a plan only → you review in the GUI → confirm Move to Trash (reversible; permanent delete is implemented nowhere). Never-trash rules + an optional "unread promos >90d" policy.

• Replies: AI drafts → you verify recipient/subject/body → press Send.

• Subscription Cleanup: header-based detection + RFC 8058 one-click unsubscribe, GUI-confirmed, no body links/cookies/redirects.

• MCP tools for Claude Code / Codex: list_recent_emails, search_emails, read_email, list_threads, create_cleanup_plan, view_cleanup_plan, request_trash_selected_items, draft_reply, request_send_draft, list_connections_status.

Safety model (the point)

The destructive code (core/execute.py for Trash/Send, core/unsubscribe.py for one-click) is imported only by the GUI, never by the MCP bridge. A prompt-injected email can at most create a queued request you will see and can reject. Full design: ARCHITECTURE.md · SECURITY.md.

Running it yourself (developer preview)

Cloning this repo does not grant Gmail access. The repo ships the public BedVibe Client ID but not the client secret (it's DPAPI-encrypted on the maintainer's machine, gitignored). To run it, use development mode with your own free Google client:

1. Google Cloud Console → new project → enable Gmail API.

2. OAuth consent screen → External, Testing → add your Gmail as a Test user.

3. Credentials → OAuth client ID → Desktop app → copy the Client ID.

4. copy app_config.example.json app_config.json, paste your Client ID (leave secret empty for PKCE).

5. python -m venv .venv ; .venv\Scripts\activate
   pip install -r requirements.txt
   python selftest.py        # structural check
   python run_app.py         # Connections → Connect Gmail (read)

Then AI Client Connections → Connect Claude Code / Codex (shows the exact config change + backs it up) and ask your AI to analyze clutter or draft a reply. Full walkthrough: DEMO.md.

Provider status

Project layout

core/         shared engine (oauth, gmail, execute, unsubscribe, safety, db, providers, …)
mcp_server/   stdio MCP bridge (10 read/prepare/queue tools)
gui/          PySide6 desktop app (9 screens)
docs/images/  screenshots
*.md          README · ARCHITECTURE · SECURITY · DEMO · CHANGELOG · RELEASE_READINESS · DISTRIBUTION_OAUTH

Documentation

ARCHITECTURE · SECURITY · DEMO · DISTRIBUTION_OAUTH · RELEASE_READINESS · CHANGELOG

Privacy

No secret, token, DPAPI file, Gmail database, log, or real message content is committed — application data lives in %APPDATA%\BedVibeMailBridge\ and is gitignored. The only credential in source is the public desktop Client ID (public by design for installed apps).

License

Proprietary / source-available — see LICENSE. Copyright (c) 2026 Panagiotis Gkilis / BedVibe Studios. All rights reserved. Published for portfolio evaluation and technical review only; no copying, modification, redistribution, hosting, training, or commercial use without prior written permission.

Maintainer / contact: Panos Gkilis · BedVibe Studios · bedvibe@bedvibe.studio

v0.1.0 developer preview. A separate packaged consumer build (Google verification + installer) is future work, not this repo.