productivity-mcp

Локальный сервер Model Context Protocol, который предоставляет LLM-клиенту (Claude Desktop, Kiro или любому приложению с поддержкой MCP) доступ на чтение/запись к вашей электронной почте и календарю.

Поддерживает:

Работает полностью на вашем компьютере через stdio. Никакие данные не покидают ваш компьютер, кроме как для отправки на настроенные вами почтовые/календарные серверы.

Установка

Требуется macOS с установленным Homebrew. Все остальное (Python 3.13, uv, git) устанавливается по требованию.

git clone https://github.com/seandkendall/productivity-mcp.git
cd productivity-mcp
./setup.sh

./setup.sh устанавливает через brew все недостающие зависимости, создает виртуальное окружение (virtualenv), устанавливает пакет и запускает интерактивный мастер настройки.

Related MCP server: multi-mail-mcp

Настройка

Запустите интерактивный мастер — он создаст venv, установит пакет, запросит ваши учетные данные и создаст конфигурационный файл:

./setup.sh

Мастер поддерживает:

• iCloud / Apple Mail — введите email + пароль приложения, готово. Настраивает и почту, и календарь.

• Gmail / Google Calendar — укажите путь к JSON-файлу клиента OAuth (см. ниже, как его получить).

• Generic IMAP — выберите пресет (Fastmail, Yahoo, Outlook) или введите свой хост/порт.

Конфигурация записывается в ~/.config/productivity-mcp/config.toml с правами доступа 0600. Запускайте мастер повторно в любое время, чтобы добавить или заменить учетные записи.

Gmail: разовая настройка Google Cloud

Google отключил пароли приложений для IMAP/SMTP в марте 2025 года, поэтому для Gmail требуется OAuth2. Перед запуском мастера:

1. Откройте Google Cloud Console → создайте или выберите проект.

2. APIs & Services → Library → включите Gmail API и Google Calendar API.

3. APIs & Services → OAuth consent screen → настройте как External (добавьте себя как тестового пользователя).

4. Credentials → Create credentials → OAuth client ID → Desktop app → скачайте JSON.

Затем запустите productivity-mcp setup, выберите Gmail и укажите путь к скачанному JSON. Первый вызов инструмента откроет браузер для авторизации; токен обновления (refresh token) кэшируется локально.

iCloud: разовая настройка Apple ID

Войдите на appleid.apple.com → Sign-In and Security → App-Specific Passwords → создайте пароль. Вставьте его в мастер при запросе.

Ручная настройка (опционально)

Если вы предпочитаете редактировать TOML напрямую, скопируйте example.config.toml в ~/.config/productivity-mcp/config.toml.

Запуск

productivity-mcp

Работает через stdio — вы подключаете его к клиенту, а не запускаете как долгоживущий демон.

Claude Desktop

Отредактируйте ~/Library/Application Support/Claude/claude_desktop_config.json:

{
 "mcpServers": {
 "productivity": {
 "command": "/absolute/path/to/.venv/bin/productivity-mcp"
 }
 }
}

Перезапустите Claude Desktop. Инструменты появятся в меню 🔌.

Kiro

В настройках Kiro добавьте MCP-сервер с командой productivity-mcp (или абсолютным путем к бинарному файлу venv). Он будет работать через stdio.

Доступные инструменты (39)

Если account опущен в любом инструменте, используется первая настроенная учетная запись этого типа. Используйте list_email_accounts / list_calendar_accounts для поиска имен и псевдонимов.

Почта — чтение и поиск

• list_email_accounts — настроенные учетные записи с их addresses (основной + псевдонимы)

• list_folders(account?) — IMAP-папки / метки Gmail

• list_emails(account?, folder="INBOX", limit=25, query?, unread_only=false, recipients?, since_days?, senders?)

• read_email(message_id, account?, folder="INBOX", format="text"|"html"|"both") — HTML-тела по умолчанию преобразуются в обычный текст

• search_threads(account?, folder="INBOX", query?, senders?, recipients?, since_days?, limit=25) — дедупликация по переписке

• search_emails_by_sender(senders, account?, folder="INBOX", since_days?, limit=25)

• count_emails(account?, folder="INBOX", query?, unread_only=false, senders?, recipients?, since_days?)

• count_unread(account?, folder="INBOX", since_days?)

• list_recent_senders(account?, folder="INBOX", since_days=30, top=20)

• summarize_inbox(account?, folder="INBOX", since_days=7, top=10) — итоги, топ отправителей, топ доменов, топ псевдонимов получателей, гистограмма по дням

• resolve_contact(query, account?, limit=10) — поиск имени/email (через Gmail People API или сканирование недавних сообщений)

Почта — запись (с ограничением частоты)

• send_email(to, subject, body, account?, cc?, bcc?, html=false)

• reply_email(message_id, body, reply_all=false, account?, folder="INBOX", html=false)

• forward_email(message_id, to, body="", account?, folder="INBOX", html=false)

• set_email_read(message_id, read=true, account?, folder="INBOX")

• delete_email(message_id, account?, folder="INBOX")

• move_email(message_id, target_folder, account?, folder="INBOX")

• bulk_set_read(message_ids, read=true, account?, folder="INBOX")

• bulk_delete_emails(message_ids, account?, folder="INBOX")

• bulk_move_emails(message_ids, target_folder, account?, folder="INBOX")

Почта — черновики и вложения

• save_draft(to, subject, body, account?, cc?, bcc?, html=false)

• list_drafts(account?, limit=25)

• send_draft(draft_id, account?)

• list_attachments(message_id, account?, folder="INBOX")

• download_attachment(message_id, attachment_id, save_to?, account?, folder="INBOX") — сохранить на диск или вернуть base64

Календарь

• list_calendar_accounts

• list_calendars(account?)

• list_events(account?, calendar?, start?, end?, limit=100) — по умолчанию следующие 7 дней

• get_event(event_id, account?, calendar?)

• search_events(query, account?, calendar?, start?, end?, limit=50)

• create_event(summary, start, end, account?, calendar?, description?, location?, attendees?)

• update_event(event_id, account?, calendar?, summary?, start?, end?, description?, location?, attendees?)

• delete_event(event_id, account?, calendar?)

• respond_event(event_id, response, account?, calendar?) — accept | decline | tentative

• free_busy(start, end, account?, attendees?) — нативный Google freebusy.query; EWS/CalDAV возвращаются к перечислению событий

• suggest_meeting_times(duration_minutes, window_start, window_end, account?, attendees?, working_hours_start=9, working_hours_end=17, limit=5)

Задачи

• list_tasks(account?, limit=50) — Google Tasks (аккаунты Google Calendar) или EWS Tasks (WorkMail)

• create_task(title, account?, due?, notes?)

Диагностика

• ping(account?) — проверка каждого настроенного аккаунта; возвращает {ok, latency_ms, error?} для каждого

Наблюдаемость

Каждый вызов инструмента выводит структурированный JSON в stderr:

{"ts":"...","level":"INFO","msg":"tool_call.start","tool":"list_emails","call_id":"b69185a6","arg_keys":["limit"]}
{"ts":"...","level":"INFO","msg":"tool_call.end","tool":"list_emails","call_id":"b69185a6","duration_ms":420}

Логируются только ключи аргументов — значения никогда не утекают. Перенаправляйте stderr в файл при отладке.

Ограничения частоты (Rate limits)

Деструктивные инструменты имеют мягкие ограничения частоты, чтобы сдержать случайные циклы LLM. Значения по умолчанию (на процесс сервера, скользящее окно):

При превышении инструмент возвращает RuntimeError с задержкой повтора. Перезапустите сервер для сброса.

Разработка

# Lint
ruff check src tests
ruff format src tests

# Tests
pytest

Безопасность

• Секреты хранятся в ~/.config/productivity-mcp/config.toml — никогда не коммитятся, никуда не передаются, кроме как на ваши настроенные почтовые/календарные серверы.

• Токены Gmail OAuth кэшируются по указанному вами пути token_file; обращайтесь с ними как с паролями.

• Для iCloud/IMAP всегда используйте пароли приложений, никогда не используйте пароль от основной учетной записи.

Лицензия

MIT

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers

Tools

• bulk_delete_emailsA
• bulk_move_emailsC
• bulk_set_readA
• count_emailsA
• count_unreadB
• create_eventC
• create_taskC
• delete_emailA