inboxfewer

README

inboxfewer

Archive Gmail threads for closed GitHub issues and provide MCP server for AI assistants

SYNOPSIS

inboxfewer [command] [options]
inboxfewer cleanup [--account ACCOUNT] [--skip-personal] [--debug]
inboxfewer serve [--transport TYPE] [--http-addr ADDR] [--yolo] [--debug]

DESCRIPTION

inboxfewer is a tool that archives Gmail threads related to closed GitHub issues and pull requests. It can run as a standalone CLI tool or as a Model Context Protocol (MCP) server, providing AI assistants with programmatic access to Gmail, Google Docs, Google Drive, Google Calendar, Google Meet, and Google Tasks.

INSTALLATION

Container Images

Run with Docker:

# Latest stable release
docker run -p 8080:8080 ghcr.io/teemow/inboxfewer:latest

# Specific version
docker run -p 8080:8080 ghcr.io/teemow/inboxfewer:v1.2.3

Deploy with Helm:

# Install from OCI registry
helm install inboxfewer oci://ghcr.io/teemow/charts/inboxfewer

# With custom configuration
helm install inboxfewer oci://ghcr.io/teemow/charts/inboxfewer \
  --set image.tag=v1.2.3 \
  --values my-values.yaml

See docs/deployment.md for comprehensive deployment documentation.

Binary Installation

Download the latest release for your platform:

# Linux (amd64)
curl -L https://github.com/teemow/inboxfewer/releases/latest/download/inboxfewer_linux_amd64.tar.gz | tar xz

# Linux (arm64)
curl -L https://github.com/teemow/inboxfewer/releases/latest/download/inboxfewer_linux_arm64.tar.gz | tar xz

# macOS (amd64)
curl -L https://github.com/teemow/inboxfewer/releases/latest/download/inboxfewer_darwin_amd64.tar.gz | tar xz

# macOS (arm64)
curl -L https://github.com/teemow/inboxfewer/releases/latest/download/inboxfewer_darwin_arm64.tar.gz | tar xz

# Install to PATH
sudo mv inboxfewer /usr/local/bin/

Or install from source:

go install github.com/teemow/inboxfewer@latest

COMMANDS

cleanup

Archive Gmail threads related to closed GitHub issues and pull requests.

inboxfewer cleanup [--account ACCOUNT] [--skip-personal]

With --skip-personal, threads that notified you personally are kept even when the issue or pull request is closed. A notification counts as personal when GitHub sets the X-GitHub-Reason header to mention, assign or author, that is: someone mentioned your handle, the issue is assigned to you, or you opened it. Notifications you received through a team mention or a review request are still archived.

inboxfewer cleanup --skip-personal

serve

Start the MCP server to provide tools for AI assistants.

inboxfewer serve [--transport TYPE] [--http-addr ADDR] [--yolo]

Transport Types:

• stdio: Standard input/output (default, for desktop apps)
• streamable-http: HTTP streaming (HTTP server on --http-addr)

version

Display version information.

inboxfewer version

generate-docs

Generate markdown documentation for all MCP tools.

inboxfewer generate-docs           # Output to stdout
inboxfewer generate-docs -o FILE   # Output to file

OPTIONS

--account ACCOUNT      Google account name to use (default: "default")
--skip-personal        Keep threads where GitHub notified you personally (cleanup only)
--debug                Enable debug logging
--transport TYPE       MCP transport: stdio, streamable-http (default: stdio)
--http-addr ADDR       HTTP server address for http transport (default: :8080)
--yolo                 Enable write operations in MCP server (default: read-only)

CONFIGURATION

GitHub Token

Create ~/keys/github-inboxfewer.token with:

<github-username> <github-personal-access-token>

Google OAuth

Authentication with Google differs by transport type:

STDIO Transport (desktop): On first run, authenticate via browser. Tokens are cached locally:

• Linux/Unix: ~/.cache/inboxfewer/google-{account}.token
• macOS: ~/Library/Caches/inboxfewer/google-{account}.token
• Windows: %TEMP%/inboxfewer/google-{account}.token

HTTP Transport (deployed): Uses OAuth 2.1 with Dynamic Client Registration. MCP clients authenticate through the server's OAuth proxy, no Google credentials needed on the client side. See docs/mcp-oauth.md for setup.

Multi-Account Support

Manage multiple Google accounts using the --account flag:

inboxfewer cleanup --account work
inboxfewer cleanup --account personal

See docs/configuration.md for details.

EXAMPLES

Archive Gmail threads for closed issues:

inboxfewer cleanup

Start MCP server for Claude Desktop:

inboxfewer serve

Start MCP server with HTTP transport:

inboxfewer serve --transport streamable-http --http-addr :8080

Enable all write operations:

inboxfewer serve --yolo

MCP SERVER

The MCP server provides 66 tools for managing Gmail, Google Docs, Drive, Calendar, Meet, and Tasks. By default, the server operates in read-only mode for safety. Use --yolo to enable write operations.

Key Capabilities:

• Gmail: List, search, archive, send emails, manage filters
• Google Docs: Retrieve document content in markdown or text
• Google Drive: Upload, download, organize, share files
• Google Calendar: Create events, check availability, schedule meetings
• Google Meet: Access recordings, transcripts, and notes
• Google Tasks: Create and manage task lists

See docs/tools.md for the complete tool reference (auto-generated from code).

FILES

~/keys/github-inboxfewer.token           GitHub credentials
~/.cache/inboxfewer/google-*.token       Google OAuth tokens (Linux/Unix)
~/Library/Caches/inboxfewer/google-*.token   Google OAuth tokens (macOS)
%TEMP%/inboxfewer/google-*.token         Google OAuth tokens (Windows)

SEE ALSO

• Configuration Guide
• Deployment Guide - Docker, Kubernetes, Helm
• MCP OAuth Guide - OAuth 2.1 authentication for HTTP transport
• Security Guide - Security best practices and compliance
• MCP Tools Reference
• Development Guide
• Debugging Guide

AUTHORS

Original concept by Brad Fitzpatrick. MCP server integration by @teemow.

LICENSE

See LICENSE file for details.

BUGS

Report bugs at: https://github.com/teemow/inboxfewer/issues