inbox-mcp
Integrates with Gmail API to search, read, label, and draft replies (never sent), with privacy masking of emails before AI processing.
Integrates with Google Calendar via OAuth2, allowing idempotent calendar event upserts (timed, all-day, multi-day) to configurable secondary calendars.
Integrates with Slack to post a digest report to a specified channel using a Bot User OAuth token.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@inbox-mcp Read my most recent unread emails and draft replies for any urgent ones"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
inbox-mcp
A privacy-preserving MCP server (built on FastMCP) that lets a coding agent (Claude Code / Codex / any MCP client) triage your inbox end to end: read & mask email → upsert calendar events → draft replies → post a digest to Slack — all driven by your own Google + Slack credentials.
Every email body, header and snippet is run through a local masking pipeline before it ever reaches the model: secrets are irreversibly redacted, contact PII is swapped for reversible tokens, and only the human-facing write paths (calendar / Slack / reply draft) restore the real values. Names go to your own model; passwords, API keys and card numbers never come back at all.
Gmail ──► [ mask ] ──► agent reasons over safe text ──► Calendar (upsert)
├──► Gmail reply DRAFT (never sent)
└──► Slack digest (one per run)Features
Unified tools with service prefixes:
gmail_*(search / read / label / reply-draft),calendar_*(idempotent upsert + list),slack_*(post a report).Masking-first: a Gitleaks-style secret pass → allowlist → PII tokenizer → in-memory vault, all in-process. See docs/masking.md.
Idempotent calendar upserts keyed by
iCalUID, so re-running never double-books. Timed, all-day and multi-day events supported.Reply drafts only — a threaded draft syncs to your mail client; the server never sends.
Apple Mail deep-links (
message://) so a digest line opens the original mail.Configurable calendar routing — define any number of categories via
GOOGLE_CALENDAR_ID_<KEY>environment variables; nothing is hardcoded.No telemetry, no external services beyond Google + Slack. Secrets stay in a local, gitignored env file.
Related MCP server: mcp-email-client
How it works
The server is stateless transport over the Google + Slack APIs plus the masking layer. It is meant to be registered with an interactive agent and driven by a prompt (e.g. a daily inbox-triage routine). Scheduling that prompt is left to you or your automation daemon — this repo ships the tools, not a scheduler. See docs/operating-handoff.md.
Requirements
Python ≥ 3.13, managed with
uvA Google OAuth Desktop-app
credential.jsonwith the Gmail API + Calendar API enabled (scopesgmail.modify+calendar)A Slack Bot User OAuth token (
xoxb-…) withchat:write, invited to your target channel(optional)
presidio-analyzer+ a spaCy model for full PERSON/LOCATION NER
Quick start
# 1. install
uv sync # add `--extra nlp` for Presidio (English-only) PERSON/LOCATION masking; names are unmasked by default
# 2. configure (secrets live OUTSIDE the repo)
cp .env.example ~/.config/inbox-mcp/.env
chmod 600 ~/.config/inbox-mcp/.env
$EDITOR ~/.config/inbox-mcp/.env # paths, Slack token, calendar IDs
# 3. run the server (first run opens a browser for Google consent → token.json)
uv run inbox-mcp
# 4. tests
uv run pytest -qRegister with an agent
Point the agent at this directory; no secrets go in the registration (the server
loads them from ~/.config/inbox-mcp/.env):
claude mcp add inbox_mcp -- uv run --directory /path/to/inbox-mcp inbox-mcp
# or
codex mcp add inbox_mcp -- uv run --directory /path/to/inbox-mcp inbox-mcpDocumentation
Doc | What |
OAuth, Slack, calendar IDs, env vars, registration | |
Every tool: inputs, outputs, read-only vs write | |
The privacy pipeline and how to extend it | |
Running this to process a real inbox (CWD, | |
A generic inbox-triage prompt to copy & personalize | |
A generic reply-voice guide to copy & personalize | |
The wrapper your scheduler injects each run (pointer + guardrails + completion sentinel) |
Security
Secrets (
credential.json,token.json,.env) are gitignored and belong in~/.config/inbox-mcp/(chmod 600) — never in the repo or agent config.Masking runs before any email content reaches the model; secrets are redacted irreversibly and never restored.
Reply drafts are never auto-sent.
Calendar writes target secondary calendars you configure, not your primary.
License
MIT.
Contributing
See CONTRIBUTING.md.
Available Tools
10 toolscalendar_list_eventsARead-onlyIdempotent
List events from the secondary calendar for calendar_key (read-only).
Returns events expanded into single instances and ordered by start time.
Inputs: data (required). Returns: result
calendar_upsert_eventAIdempotent
Create or update an event in the secondary calendar (idempotent by iCalUID).
Writes only to the secondary calendar resolved from config for
calendar_key — never the primary calendar. If an event with the same
iCalUID already exists it is updated in place; otherwise a new event is
created with that iCalUID so subsequent runs do not duplicate it.
Inputs: data (required). Returns: result
gmail_apply_labelsAIdempotent
Add and/or remove labels on specific Gmail messages by ID via batchModify. Resolves label display names to IDs (case-insensitive; system labels like UNREAD/INBOX work too). Optionally creates missing add-labels. Use to mark messages 'AI-Processed' and remove 'UNREAD'.
Inputs: params (required). Returns: result
gmail_batch_read_emailARead-onlyIdempotent
Fetch full content for up to 100 Gmail messages by ID. Returns headers and a decoded plaintext body for each (text/plain preferred; HTML is stripped to text when that's all that's available). Bodies are passed through the masking layer before return. Read-only.
Inputs: params (required). Returns: result
gmail_bulk_label_matchingAIdempotent
Search Gmail with a query, then add/remove labels on every matching message in one shot (search + batchModify). Resolves label names to IDs and can create missing add-labels. Use for bulk tagging of a query.
Inputs: params (required). Returns: result
gmail_create_reply_draftA
Create a threaded REPLY draft to an email in Gmail (it syncs to Apple Mail's Drafts via IMAP). Pass the original message's from/subject/threadId/message_id plus your composed reply body. PII tokens in the recipient/subject/body are restored to real values before saving; secrets stay redacted. Returns a self-minted RFC822 Message-ID and the Apple Mail deep link (message://) to the draft, plus the Gmail web draft URL as a fallback. Does NOT send.
Inputs: params (required). Returns: result
gmail_read_email_threadARead-onlyIdempotent
Fetch a full Gmail thread by thread ID: every message in order with headers and a decoded plaintext body. Bodies are passed through the masking layer before return. Read-only.
Inputs: params (required). Returns: result
gmail_search_email_idsARead-onlyIdempotent
Search Gmail and return only message IDs plus a pagination token. Cheaper than gmail_search_emails when you only need IDs to feed into gmail_batch_read_email or gmail_apply_labels. Read-only.
Inputs: params (required). Returns: result
gmail_search_emailsARead-onlyIdempotent
Search Gmail and return compact message summaries (id, threadId, from, subject, date, snippet, labelIds). Use Gmail search syntax. Supports pagination via page_token. Read-only; does not return full bodies.
Inputs: params (required). Returns: result
slack_postA
Post a message to Slack via chat.postMessage. Use this to deliver the final report after processing emails and registering calendar events. The bot must be a member of the target channel; if it is not, the error will tell you to invite it.
Inputs: data (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 10 tools
Most tools have clearly distinct purposes: search vs. read vs. label vs. calendar vs. Slack. Slight overlap exists between gmail_search_emails and gmail_search_email_ids (both search) and between gmail_apply_labels and gmail_bulk_label_matching (both label), but descriptions clarify the intended use cases.
All tool names use lowercase snake_case with domain prefixes (gmail_, calendar_, slack_) and a verb_noun structure. Minor deviations like 'bulk_label_matching' are still readable and follow the general pattern, so the set feels consistent.
10 tools is a well-scoped size for an inbox automation server covering email search, read, labeling, draft creation, calendar upsert/list, and Slack posting. Each tool earns its place and the count is neither thin nor bloated.
The tool surface covers the core workflow of searching and reading emails, applying labels, drafting replies, upserting calendar events, listing them, and posting to Slack. Minor gaps exist such as no email send (only draft), no calendar delete, and no Slack read, but these don't block the primary intended workflow.
Maintenance
Related MCP Connectors
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
One MCP server for all your work accounts: Slack, Teams, Google Chat, Jira, ClickUp, digest, tasks.
Hosted email MCP for your own Gmail, Outlook.com, Microsoft 365, iCloud or IMAP inbox: read, search, draft, reply in thread, forward and file mail. It moves or flags up to 500 messages in one call, and a send leaves exactly one copy in Sent. A calendar is a separate connection, and connecting one adds diary and scheduling tools.
Related MCP Servers
- AlicenseBqualityDmaintenanceA local MCP server that provides LLM clients with read/write access to email and calendar data from Gmail, iCloud, and generic IMAP providers. It runs entirely on your machine, keeping data private while enabling email management, calendar operations, and task handling through natural language.39MIT
- FlicenseNot gradedqualityDmaintenanceMCP server for email management that enables reading, searching, drafting, replying to, and sending emails with thread-aware replies and draft-first safety, supporting Gmail API and IMAP/SMTP backends.-
- AlicenseNot gradedqualityDmaintenanceA local-first MCP server for managing multiple Gmail accounts with separate OAuth grants, supporting search, retrieval, labels, drafts, and attachments while deferring direct send and destructive actions for safety.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that connects Gmail and Google Calendar to AI assistants, enabling email search, reading, sending, and calendar management across multiple accounts with secure OAuth.1MIT