Skip to main content
Glama
productivity-mcp

productivity-mcp

by seandkendall

productivity-mcp

LLM 클라이언트(Claude Desktop, Kiro, MCP 지원 앱)가 이메일 및 캘린더에 읽기/쓰기 액세스할 수 있도록 하는 로컬 Model Context Protocol 서버입니다.

지원 항목:

제공업체

이메일

캘린더

인증

Gmail

✅ (API)

✅ (Google Calendar)

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로 설치하고, 가상 환경(virtualenv)을 생성하며, 패키지를 설치하고, 대화형 구성 마법사를 실행합니다.

Related MCP server: claude-2-mail

구성

대화형 마법사를 실행하세요. 가상 환경을 생성하고 패키지를 설치한 다음, 자격 증명을 묻고 구성을 작성합니다:

./setup.sh

마법사 지원 항목:

  • iCloud / Apple Mail — 이메일 + 앱 전용 비밀번호를 입력하면 완료됩니다. 메일과 캘린더가 모두 설정됩니다.

  • Gmail / Google Calendar — OAuth 클라이언트 JSON을 지정하세요(획득 방법은 아래 참조).

  • 일반 IMAP — 사전 설정(Fastmail, Yahoo, Outlook)을 선택하거나 사용자 지정 호스트/포트를 입력하세요.

구성은 0600 권한으로 ~/.config/productivity-mcp/config.toml에 작성됩니다. 계정을 추가하거나 교체하려면 언제든지 마법사를 다시 실행하세요.

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 Calendar 계정) 또는 EWS Tasks(WorkMail)

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

진단

  • ping(account?) — 구성된 모든 계정을 프로브합니다. 계정별 {ok, latency_ms, error?}를 반환합니다.

관측 가능성

모든 도구 호출은 stderr로 구조화된 JSON을 내보냅니다:

{"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