productivity-mcp

Local Model Context Protocol server that gives an LLM client (Claude Desktop, Kiro, any MCP-aware app) read/write access to your email and calendar.

Supports:

Runs entirely on your machine, over stdio. No data leaves your computer except to your configured mail/calendar servers.

Install

Requires macOS with Homebrew installed. Everything else (Python 3.13, uv, git) is installed on demand.

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

./setup.sh brew-installs any missing prerequisites, creates a virtualenv, installs the package, and launches the interactive configuration wizard.

Configure

Run the interactive wizard — it creates a venv, installs the package, then asks for your credentials and writes the config for you:

./setup.sh

The wizard supports:

• iCloud / Apple Mail — enter your email + app-specific password, done. Sets up both mail and calendar.

• Gmail / Google Calendar — point it at your OAuth client JSON (see below for how to get one).

• Generic IMAP — pick a preset (Fastmail, Yahoo, Outlook) or enter a custom host/port.

The config is written to ~/.config/productivity-mcp/config.toml with 0600 permissions. Re-run the wizard any time to add or replace accounts.

Gmail: one-time Google Cloud setup

Google disabled IMAP/SMTP app passwords in March 2025, so Gmail requires OAuth2. Before running the wizard:

1. Open the Google Cloud Console → create or pick a project.

2. APIs & Services → Library → enable Gmail API and Google Calendar API.

3. APIs & Services → OAuth consent screen → set it up as External (add yourself as a test user).

4. Credentials → Create credentials → OAuth client ID → Desktop app → download the JSON.

Then run productivity-mcp setup, choose Gmail, and point it at the downloaded JSON. First tool call opens a browser to authorize; the refresh token is cached locally.

iCloud: one-time Apple ID setup

Sign in at appleid.apple.com → Sign-In and Security → App-Specific Passwords → generate one. Paste it into the wizard when prompted.

Manual config (optional)

If you'd rather edit TOML directly, copy example.config.toml to ~/.config/productivity-mcp/config.toml.

Run

productivity-mcp

This runs over stdio — you wire it into a client rather than running it as a long-lived daemon.

Claude Desktop

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Restart Claude Desktop. The tools appear under the 🔌 menu.

Kiro

In Kiro settings, add an MCP server with command productivity-mcp (or the absolute path to the venv binary). It will run over stdio.

Available tools (39)

If account is omitted from any tool, the first configured account of that type is used. See list_email_accounts / list_calendar_accounts to discover names and aliases.

Email — read & discovery

• list_email_accounts — configured accounts with their addresses (primary + aliases)

• list_folders(account?) — IMAP folders / Gmail labels

• 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 bodies are rendered to plaintext by default

• search_threads(account?, folder="INBOX", query?, senders?, recipients?, since_days?, limit=25) — dedupe by conversation

• 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) — totals, top senders, top domains, top recipient aliases, per-day histogram

• resolve_contact(query, account?, limit=10) — name/email lookup (Gmail People API or recent-message scan)

Email — write (rate-limited)

• 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")

Email — drafts & attachments

• 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") — save to disk or return base64

Calendar

• list_calendar_accounts

• list_calendars(account?)

• list_events(account?, calendar?, start?, end?, limit=100) — defaults to next 7 days

• 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?) — native Google freebusy.query; EWS/CalDAV fall back to event enumeration

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

Tasks

• list_tasks(account?, limit=50) — Google Tasks (Google Calendar accounts) or EWS Tasks (WorkMail)

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

Diagnostics

• ping(account?) — probe every configured account; returns per-account {ok, latency_ms, error?}

Observability

Every tool call emits structured JSON to 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}

Only argument keys are logged — values never leak. Pipe stderr to a file when debugging.

Rate limits

Destructive tools have soft rate limits to contain accidental LLM loops. Defaults (per server process, sliding window):

When exceeded the tool returns a RuntimeError with the retry delay. Restart the server to reset.

Develop

# Lint
ruff check src tests
ruff format src tests

# Tests
pytest

Security

• Secrets live in ~/.config/productivity-mcp/config.toml — never committed, never transmitted anywhere except to your configured mail/calendar servers.

• Gmail OAuth tokens are cached at the token_file path you specify; treat them like passwords.

• For iCloud/IMAP, always use app-specific passwords, never your main account password.

License

MIT