productivity-mcp
A local MCP server that provides LLM clients with read/write access to email and calendar data from Gmail, iCloud, and generic IMAP providers. It runs entirely on your machine, keeping data private while enabling email management, calendar operations, and task handling through natural language.
Ask AI about productivity-mcp
Powered by Claude Β· Grounded in docs
I know everything about productivity-mcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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:
| Provider | Calendar | Auth | |
|---|---|---|---|
| Gmail | β (API) | β (Google Calendar) | OAuth2 (desktop app) |
| Apple / iCloud | β (IMAP/SMTP) | β (CalDAV) | App-specific password |
| Generic IMAP (Fastmail, self-hosted, work mail) | β | β | Password / app password |
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:
- Open the Google Cloud Console β create or pick a project.
- APIs & Services β Library β enable Gmail API and Google Calendar API.
- APIs & Services β OAuth consent screen β set it up as External (add yourself as a test user).
- 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 theiraddresses(primary + aliases)list_folders(account?)β IMAP folders / Gmail labelslist_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 defaultsearch_threads(account?, folder="INBOX", query?, senders?, recipients?, since_days?, limit=25)β dedupe by conversationsearch_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 histogramresolve_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_accountslist_calendars(account?)list_events(account?, calendar?, start?, end?, limit=100)β defaults to next 7 daysget_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?)β native Googlefreebusy.query; EWS/CalDAV fall back to event enumerationsuggest_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):
| Tool | Limit |
|---|---|
send_email, send_draft, reply_email, forward_email | 20 / minute |
delete_email, delete_event | 20β50 / minute |
create_event, update_event | 30 / minute |
bulk_set_read, bulk_delete_emails, bulk_move_emails | 10 / minute |
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_filepath you specify; treat them like passwords. - For iCloud/IMAP, always use app-specific passwords, never your main account password.
License
MIT
