productivity-mcp

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

지원 항목:

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: multi-mail-mcp

구성

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

./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 루프를 방지하기 위한 소프트 속도 제한이 있습니다. 기본값(서버 프로세스당, 슬라이딩 윈도우):

제한을 초과하면 도구는 재시도 지연 시간이 포함된 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