Skip to main content
Glama

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 uv

  • A Google OAuth Desktop-app credential.json with the Gmail API + Calendar API enabled (scopes gmail.modify + calendar)

  • A Slack Bot User OAuth token (xoxb-…) with chat: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 -q

Register 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-mcp

Documentation

Doc

What

docs/configuration.md

OAuth, Slack, calendar IDs, env vars, registration

docs/tools.md

Every tool: inputs, outputs, read-only vs write

docs/masking.md

The privacy pipeline and how to extend it

docs/operating-handoff.md

Running this to process a real inbox (CWD, operating/, scheduling)

docs/daily-run-prompt.template.md

A generic inbox-triage prompt to copy & personalize

docs/reply-style-guide.template.md

A generic reply-voice guide to copy & personalize

docs/scheduler-inject.template.md

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 tools
calendar_list_eventsA
Read-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_eventA
Idempotent

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_labelsA
Idempotent

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_emailA
Read-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_matchingA
Idempotent

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_threadA
Read-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_idsA
Read-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_emailsA
Read-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

    A4.2/5.0

    Scored across 10 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      A 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.
      39
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP 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.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      A 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
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that connects Gmail and Google Calendar to AI assistants, enabling email search, reading, sending, and calendar management across multiple accounts with secure OAuth.
      1
      MIT