productivity-mcp
productivity-mcp
Локальный сервер Model Context Protocol, который предоставляет LLM-клиенту (Claude Desktop, Kiro или любому приложению с поддержкой MCP) доступ на чтение/запись к вашей электронной почте и календарю.
Поддерживает:
Провайдер | Почта | Календарь | Авторизация |
Gmail | ✅ (API) | ✅ (Google Calendar) | OAuth2 (десктопное приложение) |
Apple / iCloud | ✅ (IMAP/SMTP) | ✅ (CalDAV) | Пароль приложения |
Generic IMAP (Fastmail, self-hosted, рабочая почта) | ✅ | — | Пароль / пароль приложения |
Работает полностью на вашем компьютере через 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: claude-2-mail
Настройка
Запустите интерактивный мастер — он создаст 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. Перед запуском мастера:
Откройте Google Cloud Console → создайте или выберите проект.
APIs & Services → Library → включите Gmail API и Google Calendar API.
APIs & Services → OAuth consent screen → настройте как External (добавьте себя как тестового пользователя).
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-папки / метки Gmaillist_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_accountslist_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 | tentativefree_busy(start, end, account?, attendees?)— нативный Googlefreebusy.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. Значения по умолчанию (на процесс сервера, скользящее окно):
Инструмент | Лимит |
| 20 / минута |
| 20–50 / минута |
| 30 / минута |
| 10 / минута |
При превышении инструмент возвращает RuntimeError с задержкой повтора. Перезапустите сервер для сброса.
Разработка
# Lint
ruff check src tests
ruff format src tests
# Tests
pytestБезопасность
Секреты хранятся в
~/.config/productivity-mcp/config.toml— никогда не коммитятся, никуда не передаются, кроме как на ваши настроенные почтовые/календарные серверы.Токены Gmail OAuth кэшируются по указанному вами пути
token_file; обращайтесь с ними как с паролями.Для iCloud/IMAP всегда используйте пароли приложений, никогда не используйте пароль от основной учетной записи.
Лицензия
MIT
Available Tools
39 toolsbulk_delete_emailsA
Delete many emails in one call. IMAP expunges; Gmail moves to Trash. Rate-limited.
Inputs: message_ids (required), account, folder. Returns: object
bulk_move_emailsC
Move many emails to another folder/label in one call. Rate-limited.
Inputs: message_ids (required), target_folder (required), account, folder. Returns: object
bulk_set_readA
Mark many emails read/unread in one call. Returns counts of successes and failures. Rate-limited.
Inputs: message_ids (required), read, account, folder. Returns: object
count_emailsA
Count messages matching filters without fetching full envelopes. General-purpose counter — e.g. 'how many emails from Amazon this month?'
Inputs: account, folder, query, unread_only, +3 more. Returns: object
count_unreadB
Count unread messages in a folder (optionally within the last N days).
Inputs: account, folder, since_days. Returns: object
create_eventC
Create a calendar event. Times are ISO 8601.
Inputs: summary (required), start (required), end (required), account, +4 more. Returns: object
create_taskC
Create a new task. due is ISO 8601 and optional.
Inputs: title (required), account, due, notes. Returns: object
delete_emailA
Delete an email. IMAP expunges; Gmail moves to Trash (recoverable).
Inputs: message_id (required), account, folder. Returns: object
delete_eventC
Delete a calendar event by id.
Inputs: event_id (required), account, calendar. Returns: object
download_attachmentA
Download an attachment. If save_to (directory) is provided, writes the
file there and returns its path. Otherwise returns base64-encoded bytes.
Inputs: message_id (required), attachment_id (required), save_to, account, +1 more. Returns: object
forward_emailC
Forward an email to new recipients, optionally prepending a note.
Inputs: message_id (required), to (required), body, account, +2 more. Returns: object
free_busyA
Return busy time windows between start and end (ISO 8601).
If attendees is provided, queries busy times for those addresses; otherwise
returns your own busy times. Native Google freebusy.query is used for
Google Calendar; EWS / CalDAV fall back to enumerating events.
Inputs: start (required), end (required), account, attendees. Returns: result
get_eventB
Fetch a single calendar event with full detail.
Inputs: event_id (required), account, calendar. Returns: object
list_attachmentsC
List attachments on a message. Each entry has {attachment_id, filename, mime_type, size}.
Inputs: message_id (required), account, folder. Returns: result
list_calendar_accountsA
List configured calendar accounts.
Inputs: no named parameters. Returns: result
list_calendarsC
List calendars on an account.
Inputs: account. Returns: result
list_draftsC
List pending email drafts.
Inputs: account, limit. Returns: result
list_email_accountsA
List configured email accounts.
Each entry includes:
name: the account LABEL used as the
accountargument in other toolskind: provider class (ImapEmailProvider / GmailProvider)
addresses: every email address this mailbox receives mail at — the primary login address PLUS any configured aliases. Use these when answering 'who emailed me at X?' questions; the
nameis NOT the user's email address.
Inputs: no named parameters. Returns: result
list_emailsA
List messages in a folder.
Args:
account: Account label (use list_email_accounts to see options). If
omitted, the first configured account is used.
folder: Folder (IMAP) or label (Gmail). Default INBOX.
limit: Max number of messages to return. Default 25.
query: Free-text search. For Gmail, pass native Gmail operators
(e.g. from:@example.com). For IMAP this becomes a TEXT search.
unread_only: If true, only return unread messages.
recipients: Filter to messages delivered to (or Cc'd / Bcc'd to) any
of these addresses OR domains. Each entry may be a full address
(sean@nasource.com) or a bare domain (nasource.com). Use this
to answer questions like "who emails me at my alias domains?" —
pass e.g. ["nasource.com", "seankendall.com"]. OR-combined.
since_days: Only return messages newer than this many days. STRONGLY
recommended when using recipients on a large mailbox — a full-
mailbox recipient search can take minutes on accounts with tens
of thousands of messages. For "last 30 days" questions pass 30.
Inputs: account, folder, limit, query, +3 more. Returns: result
list_eventsA
List events in a time range (defaults: now → +7 days). ISO 8601 strings.
Inputs: account, calendar, start, end, +1 more. Returns: result
list_foldersC
List folders/labels for an email account.
Inputs: account. Returns: result
list_recent_sendersA
Top senders over the last N days, ordered by message count. Useful for "who has been emailing me lately?" style questions.
Inputs: account, folder, since_days, top. Returns: result
list_tasksB
List tasks from the account's task list. Supported on Google Calendar (Google Tasks) and EWS / WorkMail (Tasks folder).
Inputs: account, limit. Returns: result
move_emailC
Move an email to another folder/label.
Inputs: message_id (required), target_folder (required), account, folder. Returns: object
pingA
Probe every configured account (or just the named one). Returns per- account {name, kind, ok, latency_ms, error?} so the LLM can self-check.
Inputs: account. Returns: result
read_emailA
Fetch a single message with its body.
Args:
message_id: Provider message id from list_emails.
account: Account label (see list_email_accounts).
folder: Folder / label. Default INBOX.
format: 'text' (default) renders HTML bodies to plaintext — the
LLM-friendly default. 'html' keeps raw HTML. 'both' returns a
body_html field alongside plaintext body.
Inputs: message_id (required), account, folder, format. Returns: object
reply_emailC
Reply to an email. Set reply_all=True to include the original Cc list.
Inputs: message_id (required), body (required), reply_all, account, +2 more. Returns: object
resolve_contactA
Look up a contact by name or partial email. Returns up to limit
{name, email} matches. Gmail queries the People API; other providers fall
back to scanning recent messages. Use before send_email / create_event
when the user refers to someone by name ("email Alice").
Inputs: query (required), account, limit. Returns: result
respond_eventB
Respond to a meeting invitation. response: accept | decline | tentative.
Inputs: event_id (required), response (required), account, calendar. Returns: object
save_draftA
Save an email as a draft instead of sending. Useful when the LLM should let the human review before committing to send. Returns {draft_id}.
Inputs: to (required), subject (required), body (required), account, +3 more. Returns: object
search_emails_by_senderC
List emails from specific senders or sender domains.
Each senders entry may be a full address (alice@example.com) or a bare
domain (example.com). OR-combined.
Inputs: senders (required), account, folder, since_days, +1 more. Returns: result
search_eventsA
Substring search across calendar events (summary, location, description). Default window: now → +60 days.
Inputs: query (required), account, calendar, start, +2 more. Returns: result
search_threadsA
List conversations (not individual messages) matching the filters.
Returns one entry per thread, with the latest message's metadata plus a
message_count field. Gmail uses native threadId; IMAP uses the Message-Id
/ References chain to group. Use this when the user asks "who has been
discussing X?" and you want to avoid seeing 15 near-duplicates of one reply
chain.
Inputs: account, folder, query, senders, +3 more. Returns: result
send_draftC
Send an existing draft by id.
Inputs: draft_id (required), account. Returns: object
send_emailC
Send an email. Returns the provider message id.
Inputs: to (required), subject (required), body (required), account, +3 more. Returns: object
set_email_readC
Mark an email as read (read=True) or unread (read=False).
Inputs: message_id (required), read, account, folder. Returns: object
suggest_meeting_timesA
Find time slots where everyone listed in attendees is free.
Combines each attendee's busy windows (via free_busy) with simple working-
hours filtering. If attendees omitted, uses your own busy times.
Inputs: duration_minutes (required), window_start (required), window_end (required), account, +4 more. Returns: result
summarize_inboxA
One-call inbox overview. Returns counts, top senders, top recipient
addresses (useful when multiple aliases hit the same mailbox), and a
per-day histogram for the last since_days days.
Inputs: account, folder, since_days, top. Returns: object
update_eventB
Update an existing event. Pass only the fields you want to change. Times (start/end) are ISO 8601.
Inputs: event_id (required), account, calendar, summary, +5 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 39 tools
Each tool has a clearly distinct purpose. Single vs bulk operations are explicitly separated, email, calendar, task, and contact tools are grouped by domain, and search utilities have specific scopes (by sender, threads, events). No two tools appear to overlap in functionality.
All tools follow a consistent verb_noun pattern with lowercase underscores (e.g., 'create_event', 'list_emails', 'delete_event'). No mixing of camelCase or other conventions, making it easy for an agent to predict tool names.
With 39 tools covering email, calendar, tasks, and contacts, the count is on the higher side but still reasonable for a comprehensive productivity suite. Each tool serves a distinct purpose, and the breadth is justified by the domain's complexity.
The tool surface is largely complete, covering CRUD for email (including bulk operations and drafts) and calendar (including free/busy and suggestion), plus tasks and contacts. Minor gaps like missing update/delete for tasks are not critical for most use cases.
Maintenance
Related MCP Connectors
Your IMAP mailbox as an MCP server: read, search and (if you allow it) organize mail. Open source.
Email infrastructure for AI agents — send, receive, search, and reply to email over MCP.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Hosted Google Calendar MCP server for AI agents. No self-hosting or Google Cloud setup.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvider-agnostic email MCP server that connects any IMAP mailbox to AI assistants, enabling email management through natural language.8AGPL 3.0
- AlicenseNot gradedqualityCmaintenanceLocal MCP server for reading/sending email via Gmail and managing Google Calendar events, enabling an AI agent to handle email and calendar operations through natural language.MIT
- FlicenseNot gradedqualityBmaintenanceA private, single-user MCP server that unifies Gmail, Microsoft 365/Outlook, and IMAP mailboxes for LLMs to search and read emails live, without storing or caching mailbox contents.-
- AlicenseNot gradedqualityAmaintenanceA local MCP server that unifies email and calendar management across multiple providers, enabling AI agents to search, read, and write with explicit approval and local-first security.2Apache 2.0