Skip to main content
Glama
productivity-mcp

productivity-mcp

by seandkendall

productivity-mcp

LLMクライアント(Claude Desktop、Kiro、その他MCP対応アプリ)にメールとカレンダーへの読み取り/書き込みアクセスを提供する、ローカルのModel Context Protocolサーバーです。

対応プロバイダー:

プロバイダー

メール

カレンダー

認証

Gmail

✅ (API)

✅ (Googleカレンダー)

OAuth2 (デスクトップアプリ)

Apple / iCloud

✅ (IMAP/SMTP)

✅ (CalDAV)

アプリ固有パスワード

汎用IMAP (Fastmail, 自前ホスト, 職場のメール)

✅

—

パスワード / アプリパスワード

すべてローカルマシン上でstdioを介して実行されます。設定したメール/カレンダーサーバー以外にデータが送信されることはありません。


インストール

HomebrewがインストールされたmacOSが必要です。その他の必要なもの(Python 3.13, uv, git)は必要に応じてインストールされます。

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

./setup.sh は不足している前提条件をbrewでインストールし、仮想環境を作成し、パッケージをインストールして、対話型設定ウィザードを起動します。

Related MCP server: claude-2-mail

設定

対話型ウィザードを実行してください。仮想環境の作成、パッケージのインストールを行い、認証情報を尋ねて設定ファイルを自動生成します:

./setup.sh

ウィザードは以下に対応しています:

  • iCloud / Apple Mail — メールアドレスとアプリ固有パスワードを入力するだけで完了します。メールとカレンダーの両方を設定します。

  • Gmail / Googleカレンダー — OAuthクライアントJSONを指定します(取得方法は下記参照)。

  • 汎用IMAP — プリセット(Fastmail, Yahoo, Outlookなど)を選択するか、カスタムのホスト/ポートを入力します。

設定は ~/.config/productivity-mcp/config.toml に 0600 パーミッションで書き込まれます。アカウントの追加や置き換えが必要な場合は、いつでもウィザードを再実行してください。

Gmail: Google Cloudの初回設定

Googleは2025年3月にIMAP/SMTPのアプリパスワードを廃止したため、GmailにはOAuth2が必要です。ウィザードを実行する前に:

  1. Google Cloud Console を開き、プロジェクトを作成または選択します。

  2. APIとサービス → ライブラリ → Gmail API と Google Calendar API を有効にします。

  3. APIとサービス → OAuth同意画面 → 外部として設定します(自分自身をテストユーザーとして追加)。

  4. 認証情報 → 認証情報を作成 → OAuthクライアントID → デスクトップアプリ → JSONをダウンロードします。

その後、productivity-mcp setup を実行し、Gmailを選択してダウンロードしたJSONを指定します。最初のツール呼び出し時にブラウザが開いて認証を求められ、リフレッシュトークンがローカルにキャッシュされます。

iCloud: Apple IDの初回設定

appleid.apple.com にサインインし、サインインとセキュリティ → アプリ固有パスワード からパスワードを生成します。ウィザードで求められたら貼り付けてください。

手動設定(オプション)

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の設定で、コマンド productivity-mcp(または仮想環境バイナリへの絶対パス)を指定してMCPサーバーを追加します。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) — 名前/メールアドレスの検索(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カレンダーアカウント)または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をファイルにパイプしてください。

レート制限

破壊的なツールには、LLMの誤作動によるループを防ぐためのソフトレート制限があります。デフォルト(サーバープロセスごと、スライディングウィンドウ):

ツール

制限

send_email, send_draft, reply_email, forward_email

20 / 分

delete_email, delete_event

20–50 / 分

create_event, update_event

30 / 分

bulk_set_read, bulk_delete_emails, bulk_move_emails

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 tools
bulk_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 account argument in other tools

  • kind: 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 name is 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

    B3.4/5.0

    Scored across 39 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count4/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provider-agnostic email MCP server that connects any IMAP mailbox to AI assistants, enabling email management through natural language.
      8
      AGPL 3.0
    • A
      license
      Not graded
      quality
      C
      maintenance
      Local 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
    • F
      license
      Not graded
      quality
      B
      maintenance
      A 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.
      -
    • A
      license
      Not graded
      quality
      A
      maintenance
      A 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.
      2
      Apache 2.0