Gmail MCP

Lokalna, rozwijana w Pythonie usługa MCP do prywatnej pracy z Gmailem. Projekt portfolio pokazuje integrację OAuth 2.0, architekturę heksagonalną i bezpieczne przygotowanie pod analizę GenAI (OpenAI lub Claude).

Aktualny etap: gotowy lokalny OAuth Gmail oraz zarządzanie aktywnym filtrem z dostępem tylko do odczytu. Serwer MCP, pobieranie wiadomości, podsumowania AI i harmonogram są kolejnymi etapami MVP — nie są jeszcze dostępne.

Co działa

• Lokalny flow OAuth 2.0 dla jednego aktywnego konta Gmail naraz, uruchamiany w przeglądarce; docelowo lokalne filtry są odseparowane per konto.
• Wyłącznie scope https://www.googleapis.com/auth/gmail.readonly.
• Polecenia do połączenia, sprawdzenia statusu i lokalnego odłączenia konta.
• Token OAuth poza repozytorium, w prywatnym katalogu danych użytkownika.
• Ochrona przed symlinkami dla pliku credentials i tokenu oraz ograniczone uprawnienia tokenu (0600 na systemach POSIX).
• Konfiguracja przyszłego dostawcy AI: OpenAI domyślnie lub Claude, bez wymogu klucza AI do OAuth.

Wymagania

• Python 3.12
• uv
• Konto Google oraz projekt Google Cloud z włączonym Gmail API

Instalacja

git clone git@github.com:under34/mcp-gmail.git
cd mcp-gmail
uv sync --locked
cp .env.example .env

Uruchomienie kontroli jakości:

uv run pytest -q
uv run ruff check .

Konfiguracja Google OAuth

1. W Google Cloud utwórz lub wybierz projekt.
2. Włącz Gmail API.
3. Skonfiguruj ekran zgody OAuth. Dla trybu testowego dodaj własny adres jako test user.
4. Utwórz OAuth Client ID typu Desktop app i pobierz plik JSON.
5. Zapisz go poza checkoutem, np. ~/secure/gmail-credentials.json.
6. Ustaw w lokalnym .env jego bezwzględną ścieżkę:

GMAIL_CREDENTIALS_PATH=/absolute/path/to/gmail-credentials.json

Plik credentials musi być zwykłym plikiem, bez symlinków i poza repozytorium. Nie dodawaj go do Git.

Polecenia Gmail

# Przy braku używalnego tokenu otwiera przeglądarkę i wykonuje lokalny flow OAuth.
uv run gmail-mcp connect-gmail

# Sprawdza zapisane połączenie; nie otwiera przeglądarki.
uv run gmail-mcp gmail-status

# Usuwa wyłącznie lokalny token OAuth. Nie cofa dostępu w Google i nie zmienia maili.
uv run gmail-mcp disconnect-gmail

# Pokazuje liczbę wątków przed zapisem filtra.
uv run gmail-mcp preview-gmail-filter --query 'from:boss@example.com'

# Ponownie sprawdza i zapisuje filtr wyłącznie po jawnym potwierdzeniu.
uv run gmail-mcp set-gmail-filter --query 'label:work' --confirm

# Pokazuje filtr aktywny dla bieżącego konta i stan lokalnego dostawcy AI.
uv run gmail-mcp gmail-filter-status
uv run gmail-mcp ai-provider-status

Po poprawnym połączeniu pierwsze polecenie wyświetli adres połączonego konta. Jeżeli token jest nieważny lub cofnięty, narzędzie zwróci bezpieczny komunikat z instrukcją ponownego połączenia. disconnect-gmail działa także wtedy, gdy oryginalny plik credentials nie jest już dostępny.

Zmienne środowiskowe

Zmienna	Cel
GMAIL_CREDENTIALS_PATH	Wymagany wyłącznie dla connect-gmail; ścieżka do pobranego pliku OAuth poza repozytorium.
GMAIL_MCP_DATA_DIR	Opcjonalne lokalne nadpisanie katalogu danych; musi znajdować się poza checkoutem.
AI_PROVIDER	Przyszły dostawca podsumowań: openai (domyślnie) lub claude.
OPENAI_API_KEY	Klucz wymagany później, gdy wybrano openai.
ANTHROPIC_API_KEY	Klucz wymagany później, gdy wybrano claude.

Zmienne procesu mają pierwszeństwo przed .env. OAuth nie wymaga żadnego klucza OpenAI ani Anthropic.

Bezpieczeństwo i prywatność

• Aplikacja nie wysyła, nie usuwa ani nie modyfikuje wiadomości Gmail.
• Nie loguje tokenów, kodów OAuth, treści maili ani załączników.
• Token, przyszła baza SQLite i digesty pozostają w lokalnym katalogu danych użytkownika (platformdirs), poza checkoutem.
• disconnect-gmail usuwa tylko lokalny token. Jeśli chcesz cofnąć dostęp po stronie Google, zrób to w ustawieniach bezpieczeństwa konta Google.

Architektura i roadmapa

Kod jest podzielony na warstwy domain, application, adapters i bootstrap. Szczegóły decyzji oraz plan prac znajdują się w _bmad-output/planning-artifacts.

Następne kroki MVP:

1. Konfiguracja filtra Gmail i wyboru dostawcy AI.
2. Odczyt oraz deduplikacja wątków, następnie podsumowania OpenAI/Claude.
3. Lokalny harmonogram digestów.
4. Serwer FastMCP z narzędziami do odczytu digestu i analizy ad hoc.

Licencja

Projekt hobbystyczny/portfolio. Licencja zostanie dodana przed publiczną dystrybucją.