poczta-mcp

Pakiet npm: @prbartosh/poczta-mcp. Komendy: npx -y @prbartosh/poczta-mcp <setup|install|server|doctor|digest|oauth>. Binarka po globalnej instalacji nazywa sie poczta-mcp.

Serwer MCP do obslugi wielu skrzynek pocztowych (IMAP/SMTP) z jednego miejsca, instalowany przez npx. Plus codzienny przeglad: agent zbiera nieprzeczytane, mowi co wazne i co wymaga akcji, dostarcza podsumowanie i oznacza jako przeczytane tylko maile bez akcji. Oraz skill mail-brief (instalowany automatycznie) do przegladu poczty na zadanie.

Obsluga auth: zwykle haslo / app-password (AGH, firmowe IMAP), Gmail OAuth2, Microsoft 365 OAuth2 (basic auth IMAP w M365 jest wycofany, dlatego OAuth2).

Jak to dziala

• poczta-mcp to lokalny serwer MCP (transport stdio). Wystawia tooly do poczty, sam z siebie nic nie robi cyklicznie.
• Codzienny automat = osobny scheduled agent (claude -p z lokalnego crona) ktory uzywa tych tooli i skilla daily-briefing.
• Wszystko lokalnie: config i hasla nie wychodza na zewnatrz. "Podglad zewszad" robi sie przez kanal digestu (mail do siebie / Slack), a nie przez hostowanie serwera.

Tooly

| Tool | Opis | |---|---| | list_accounts | lista skonfigurowanych kont | | get_unread | nieprzeczytane; bez account ze WSZYSTKICH kont | | get_email_body | pelna tresc maila (account + uid) | | search_emails | szukanie po nadawcy/temacie/dacie | | mark_as_read | oznacz przeczytane (batch uid per konto) | | send_email | wyslij (tylko po potwierdzeniu; poza przegladem) | | deliver_digest | dostarcz podsumowanie kanalami z config | | get_folders | lista folderow IMAP konta | | check_update | sprawdza czy jest nowsza wersja poczta-mcp w npm |

Wymagania

• Node >= 20.12
• Claude Code CLI (do codziennego automatu) albo Claude Desktop (do recznego uzycia)

Instalacja i konfiguracja

npx poczta-mcp setup

Wizard pyta o konta i kanaly, zapisuje:

• config.json — struktura (konta, hosty, porty, kanaly digestu). Bez sekretow, tylko NAZWY zmiennych env.
• .env — sekrety (hasla, client secret, refresh token). W .gitignore.

Ponowne setup wykrywa istniejacy config.json i wchodzi w menu (nie zaczyna od zera): dodaj konto / usun konto / zmien kanaly podsumowania / test polaczen / zapisz. Edycja jednego konta nie rusza sekretow pozostalych.

Test polaczen:

npx poczta-mcp doctor        # sprawdza auth kazdego konta + pokazuje status wersji
npx poczta-mcp digest        # surowy (bez AI) digest -> kanaly, do testu pipeline

doctor przy nieudanym polaczeniu pisze jawny komunikat (ktore konta i dlaczego) i konczy sie kodem != 0 (przerwanie), wiec cron/automat to wychwyci.

Reczna edycja zamiast wizarda: skopiuj config.example.json -> config.json i .env.example -> .env.

Globalna instalacja + rejestracja w agencie

npx poczta-mcp install     # lub: node dist/index.js install

• Opcjonalnie npm i -g (komenda poczta-mcp globalnie). Jak odmowisz, wpis uzyje node <abs sciezka>/dist/index.js.
• Rejestruje serwer MCP (multiselect) w:
  • Claude Code — przez claude mcp add poczta -s user (fallback: ~/.claude.json),
  • Claude Desktop — claude_desktop_config.json (restart aplikacji),
  • Codex CLI — ~/.codex/config.toml ([mcp_servers.poczta]).
• Wpis zawiera POCZTA_MCP_CONFIG i POCZTA_MCP_ENV (absolutne sciezki do Twojego config.json / .env), wiec dziala niezaleznie od katalogu.
• Razem z serwerem instaluje sie automatycznie skill mail-brief do ~/.claude/skills/mail-brief/ (przeglad poczty na zadanie, patrz sekcja "Skill mail-brief").

Po instalacji zrestartuj klienta i zapytaj agenta np. "co mam nieprzeczytane".

Sciezki config

Domyslnie ./config.json i ./.env w katalogu uruchomienia. Nadpisanie: POCZTA_MCP_CONFIG=/abs/config.json, POCZTA_MCP_ENV=/abs/.env.

Auth per dostawca

Password / app-password (AGH, firmowe IMAP)

W panelu webmail wygeneruj app password (AGH: Ustawienia -> Hasla do aplikacji). Wpisz do .env pod nazwa z passwordEnv.

Gmail — dwie drogi

A) App-password (najprostsze, jak email+haslo w Thunderbird). Wymaga 2FA na koncie Google.

1. myaccount.google.com -> Bezpieczenstwo -> wlacz weryfikacje 2-etapowa.
2. Haslo do aplikacji (App passwords) -> Mail -> skopiuj 16 znakow.
3. W Gmailu wlacz IMAP (Ustawienia -> Przekazywanie i POP/IMAP).
4. W kreatorze wybierz Gmail -> "App-password". To NIE jest zwykle haslo konta. (Uwaga: Thunderbird "tylko email+haslo" dziala bo ma wbudowany wlasny clientId i robi OAuth w tle. Tu odpowiednik bez clientId to app-password.)

B) OAuth2. Kreator otwiera przegladarke i sam zlapie refresh token (loopback).

1. Google Cloud Console -> projekt -> OAuth consent screen (Test user + scope https://mail.google.com/).
2. Credentials -> OAuth client typu Desktop app -> masz clientId i client secret.
3. Kreator (Gmail -> OAuth2) otworzy przegladarke, klikasz zgode, token laduje do .env. Samodzielnie: npx poczta-mcp oauth google.

Microsoft 365 (OAuth2)

Azure Portal -> Microsoft Entra ID -> App registrations -> New registration.

• tenantId, clientId -> config.json; client secret -> .env.
• Dwa tryby (auth.flow w config):
  • refresh (delegowany): API permissions (delegated) IMAP.AccessAsUser.All, SMTP.Send, offline_access. W Authentication dodaj platforme "Mobile and desktop applications" z redirect http://localhost:3000. Kreator (M365 -> refresh) otworzy przegladarke i zlapie token. Samodzielnie: npx poczta-mcp oauth microsoft.
  • client_credentials (app-only, bez uzytkownika, pod automat): permission application IMAP.AccessAsUser.All + zgoda admina, oraz per-skrzynka New-ApplicationAccessPolicy w Exchange Online PowerShell.
• SMTP M365: host smtp.office365.com, port 587, secure:false (STARTTLS).

Codzienny automat

1. Skopiuj skilla do projektu:

   mkdir -p .claude/skills && cp -r skills/daily-briefing .claude/skills/daily-briefing

2. Skopiuj .mcp.json.example -> .mcp.json, uzupelnij sciezki do config.json i .env.
3. Test recznie:

   claude -p "Wykonaj skill daily-briefing." --allowedTools "mcp__poczta__get_unread mcp__poczta__get_email_body mcp__poczta__mark_as_read mcp__poczta__deliver_digest mcp__poczta__list_accounts"

4. Cron: patrz cron.example.

Regula oznaczania (w skillu): 🔴 wazne i 🟠 wymaga akcji zostaja unread; 🟡 warto wiedziec i ⚪ opcjonalne -> oznaczone przeczytane. send_email nie jest na liscie allowedTools przegladu.

Skill mail-brief

Przeglad poczty na zadanie (nie z crona). Instaluje sie automatycznie z serwerem (poczta-mcp install) do ~/.claude/skills/mail-brief/. Wywolanie: popros agenta o przeglad / podsumowanie poczty. Tresc skilla:

Sprawdź jakie maile są dostepne w serwerze mcp i przygotuj podsumowanie dla każdego z dostępnych maili. Przeczytaj nowe maile i przygotuj zwięzłe podsumowanie, oznaczając wszystko, co wymaga działania.

🔴 Wymaga działania (X)

• [Temat] od [Nadawca] — [jedno zdanie, dlaczego wymaga działania]

🟡 Warto przeczytać (X)

• [Temat] od [Nadawca] - [jednozdaniowe podsumowanie]

⚪ Niski priorytet (X) - pomijane, chyba że użytkownik poprosi

Zwięźle, neutralnie. Myśl jak o codziennym przeglądzie, nie wypracowaniu. Po przedstawieniu briefingu wywołaj mark_as_read dla wszystkich przetworzonych UID, aby nie pojawiały się ponownie jutro. Najpierw poproś o potwierdzenie.

Roznica vs daily-briefing: mail-brief jest reczny i po potwierdzeniu oznacza przeczytane wszystkie przetworzone UID; daily-briefing chodzi z crona i zostawia unread to co wazne / wymaga akcji.

Podglad w Claude Desktop (reczne uzycie)

~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "poczta": {
      "command": "npx",
      "args": ["-y", "poczta-mcp", "server"],
      "env": { "POCZTA_MCP_CONFIG": "/abs/config.json", "POCZTA_MCP_ENV": "/abs/.env" }
    }
  }
}

Pytaj np. "co mam nieprzeczytane na wszystkich kontach", "podsumuj poczte".

Bezpieczenstwo

• .env i config.json w .gitignore. Sekrety tylko w .env.
• Serwer lokalny (stdio). Brak wystawiania po sieci = brak zewnetrznej powierzchni ataku.
• send_email poza przegladem i tylko po potwierdzeniu tresci.

Stary jednoplikowy serwer Python jest w legacy/.