Majordomo — Assistente Pessoal Self-Hosted
purroy/majordomo
Assistente pessoal self-hosted com mail, calendário, Slack e briefings automáticos
Ver no GitHubMCP Server que implementa um assistente pessoal self-hosted para Claude Code, integrando e-mail (IMAP/SMTP), calendário, Google Drive e Slack. Oferece leitura, triagem e redação de mensagens, resumos agendados (morning/evening briefings) e notificações inteligentes via Telegram ou notificações nativas, sempre com confirmação explícita antes de ações de escrita.
Instalação
npx convez-ai purroy/majordomo1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Automatizar triagem e resposta de e-mails com inteligência de priorização
- Gerar resumos matutinos e noturnos de e-mails, calendário e Slack
- Gerenciar múltiplas contas de e-mail e calendários via Claude Code
- Receber notificações em Telegram sobre itens críticos e importantes
Veredito

Ferramenta robusta para quem quer máximo controle sobre automação pessoal sem depender de SaaS. Requer conhecimento técnico (Python, IMAP/SMTP, ambiente local) e infraestrutura própria, mas oferece privacidade e customização profunda via Claude Code.
README
A tradução para o português deste README ainda está na fila.
PA — Personal Assistant on Claude Code
A self-hosted personal assistant that runs on top of Claude Code. It reads your mail (IMAP/SMTP), calendar, drive, and Slack; triages inbound; drafts replies; and sends you scheduled briefings — always with explicit confirmation before any write action.
Features
- Mail — list, read, triage, draft, and send replies over plain IMAP/SMTP (stdlib only, no external Python deps).
- Multi-account — one Keychain / env prefix per mailbox (
PA-mail-<id>-*). - Calendar / Drive / Slack — read and write via the Claude Code MCP connectors.
- Scheduled briefings — morning and evening summaries wrapped by
scripts/run_briefing.sh, optionally pushed to Telegram and macOS notifications. - Watchers — mail and Slack pollers that only wake Claude when there's actually something new, and only notify on classified "fire" or "important" items.
- Telegram bridge — two-way chat with the PA from your phone, via a long-polling bot that shells out to
claude --printper message.
Requirements
- macOS (primary target) or Linux.
- Python 3.10+ (stdlib only).
- Claude Code CLI (
claude) on$PATH. - IMAP + SMTP credentials for your mailbox(es).
- Optional: a Telegram bot token (
@BotFather) for the mobile bridge. - Optional: authenticated Claude Code MCP connectors for Google Calendar, Google Drive, and Slack.
Architecture
┌──────────────────────────┐
│ You (CLI) │
│ /morning /inbox /reply … │
└────────────┬─────────────┘
│
┌──────────────────▼──────────────────┐
│ Claude Code (claude) │
│ CLAUDE.md + .claude/commands/*.md │
└─┬─────────┬──────────┬────────────┬─┘
│ │ │ │
┌───────▼──┐ ┌───▼────┐ ┌──▼─────┐ ┌───▼──────┐
│ scripts/ │ │ MCP │ │ MCP │ │ MCP │
│ mail_* │ │Calendar│ │ Drive │ │ Slack │
└────┬─────┘ └────────┘ └────────┘ └──────────┘
│
┌────────▼────────┐
│ IMAP / SMTP │
│ (your server) │
└─────────────────┘
┌─────────── launchd (macOS) ────────────┐
│ │
run_briefing.sh morning/evening mail_watcher.py / slack_watcher.py
│ │
└──────────┐ ┌─────────────┘
▼ ▼
┌──────────────────────────┐
│ notify.sh · Telegram │
└──────────────────────────┘
Setup
1. Clone and install
git clone https://github.com/purroy/majordomo.git
cd majordomo
No pip install needed — the mail client is stdlib only.
2. Credentials
Pick one of the two mechanisms. The scripts check env vars first and fall back to Keychain on macOS.
macOS Keychain — interactive per-account wizard:
bash scripts/account_add.sh example you@example.com mail.example.com 993 mail.example.com 587 "Your Name"
This stores PA-mail-example-{user,pass,imap-host,imap-port,smtp-host,smtp-port,from-name} and appends example to the PA-mail-accounts index.
Linux / Docker — copy .env.example to .env and fill it in:
cp .env.example .env
$EDITOR .env
Never commit .env. It is in .gitignore.
3. Claude Code MCP connectors
Launch Claude Code in this directory and run:
/auth
The command diagnoses which of Calendar / Drive / Slack are authenticated and walks you through the OAuth flow for the missing ones.
4. Smoke test
/auth # diagnostics
/morning # manual briefing
5. Telegram bridge (optional)
bash scripts/telegram_setup.sh
The script asks for your @BotFather token, captures your chat id on first message, sends a test message, and loads the launchd agent so the bot runs on login.
6. Scheduled briefings, mail watcher, Slack watcher (optional)
Sample launchd plists live in scripts/launchd/. They contain __REPO_DIR__ / __USER__ / __HOME__ placeholders — install them via the wrapper, which substitutes the real values:
bash scripts/launchd/install.sh # install all agents
bash scripts/launchd/install.sh briefing-morning # just one (substring match)
bash scripts/launchd/install.sh briefing-morning briefing-evening
The wrapper runs launchctl unload then launchctl load on each agent, so re-running it is safe.
On Linux, wire scripts/run_briefing.sh, scripts/mail_watcher.py, scripts/slack_watcher.py, and scripts/telegram_bot.py to systemd timers or cron entries pointing at the same wrapper.
Layout
CLAUDE.md persona, language, confirmation rule
.claude/commands/ slash commands: /morning /evening /inbox /reply /schedule /book /auth
scripts/ IMAP/SMTP client, Keychain helpers, watchers, Telegram bridge
scripts/launchd/ sample macOS agent plists
.env.example non-secret template for Linux / Docker
briefings/ daily output (gitignored)
drafts/ unsent .eml drafts (gitignored)
Philosophy
- Explicit confirmation before any send / create.
- No secrets in the repo — Keychain or
.env. - Reuse what exists — MCP connectors for Google / Slack, Python stdlib for mail.
- Cheap polling — watchers do the bare IMAP work themselves and only wake Claude when headers changed.
Support
This is a personal setup, published as-is under MIT. No support guarantee. Issues and pull requests are welcome — fix bugs, add providers, share hardening — but do not expect replies on a schedule.