# productivity-mcp

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

Supports:

| Provider                                            |     Email      |       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](https://brew.sh) installed. Everything else (Python 3.13, uv, git) is installed on demand.

```bash
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:

```bash
./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](https://console.cloud.google.com) → 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](https://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

```bash
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`:

```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:

```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}
```

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

```bash
# 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