@kbzowski/mcp-inbox 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +100 -175
  2. package/dist/app.js +1 -1
  3. package/package.json +1 -1
package/README.md CHANGED
@@ -1,208 +1,133 @@
1
1
  # mcp-inbox
2
2
 
3
- > MCP server that gives any MCP-capable agent read/write access to your IMAP inbox, with a local SQLite cache for fast responses and IMAP IDLE for real-time updates.
3
+ MCP server for IMAP/SMTP mail: read, search, compose, send, manage drafts and flags. Backed by a local SQLite cache with IMAP IDLE, so most reads never touch the network.
4
4
 
5
- Works with any IMAP/SMTP provider: Gmail, Outlook, Fastmail, iCloud, Proton Mail (via Bridge), Dovecot, hosted Exchange, self-hosted mail servers. Tools for listing and searching mail, composing and sending, managing drafts, inspecting attachment metadata. Cache stays in sync with the server via CONDSTORE + IDLE so most reads serve from local SQLite without a network round-trip.
5
+ Works with any IMAP provider - Gmail, Outlook, Fastmail, iCloud, Proton (via Bridge), Dovecot, Exchange.
6
6
 
7
- **On attachments:** `imap_get_email` surfaces attachment metadata (filename, content type, size) by default - enough for the agent to describe what's attached without any download. When the agent genuinely needs to read content inside an attachment (search a PDF, extract a table from a CSV), `imap_get_attachment` fetches the bytes inline as base64 for one response. Nothing is cached on disk; re-requesting the same attachment refetches from the server.
7
+ ## Add it to your agent
8
8
 
9
- ---
9
+ Node 24+. Nothing to install; the agent starts the server itself through `npx`.
10
10
 
11
- ## Requirements
12
-
13
- - **Node.js 24 LTS** or newer (`node --version` should print `v24.x` or higher).
14
- - An IMAP/SMTP account. Gmail and Outlook users need an **app password**, not the account password - see [Provider notes](#provider-notes).
15
-
16
- ---
17
-
18
- ## Configure
19
-
20
- mcp-inbox reads credentials from environment variables. At minimum you need three:
21
-
22
- ```
23
- IMAP_USER=you@example.com
24
- IMAP_PASSWORD=your-app-password
25
- IMAP_HOST=imap.example.com
26
- ```
27
-
28
- The full list of variables (ports, TLS flags, cache tuning, IDLE folders) lives in [.env.example](.env.example).
29
-
30
- How those env vars reach the server process depends on which MCP client you use. Every client below lets you set env per-server.
31
-
32
- ---
33
-
34
- ## Compatible clients
35
-
36
- Works with any MCP-capable client over stdio. Confirmed integrations:
37
-
38
- | Client | Notes |
39
- |---|---|
40
- | **Claude Code** (CLI) | `claude mcp add` |
41
- | **Claude Desktop** | `claude_desktop_config.json` |
42
- | **Cursor** | Settings UI or `~/.cursor/mcp.json` |
43
- | **VS Code** | Native MCP via `.vscode/mcp.json` |
44
- | **Cline** | `cline_mcp_settings.json` |
45
- | **Continue.dev** | `~/.continue/config.yaml` |
46
- | **Codex CLI** (OpenAI) | `~/.codex/config.toml` |
47
- | **Zed** | `context_servers` in editor settings |
48
- | **Goose** (Block) | `~/.config/goose/config.yaml` |
49
- | **Thunderbird** | Via [Claude Email Search plugin](thunderbird-plugin/) — Claude CLI only |
50
-
51
- For per-client config snippets see **[docs/clients.md](docs/clients.md)**.
52
-
53
- ---
54
-
55
- ## Provider notes
56
-
57
- ### Gmail / Google Workspace
58
-
59
- Use an **[app password](https://myaccount.google.com/apppasswords)**, not your account password. Requires 2-Step Verification turned on first.
60
-
61
- ```
62
- IMAP_HOST=imap.gmail.com
63
- IMAP_PORT=993
64
- SMTP_HOST=smtp.gmail.com
65
- SMTP_PORT=465
66
- SMTP_SECURE=true
67
- ```
68
-
69
- ### Outlook / Microsoft 365
70
-
71
- ```
72
- IMAP_HOST=outlook.office365.com
73
- IMAP_PORT=993
74
- SMTP_HOST=smtp.office365.com
75
- SMTP_PORT=587
76
- SMTP_SECURE=false
77
- ```
78
-
79
- Outlook rejects the default `SMTP_PORT=465` setting - both `SMTP_PORT=587` and `SMTP_SECURE=false` are required. Personal accounts need an [app password](https://account.microsoft.com/security) if 2FA is on.
80
-
81
- ### Fastmail
82
-
83
- Use an [app password](https://app.fastmail.com/settings/security/devicekeys/add) (account-level passwords are rejected).
84
-
85
- ```
86
- IMAP_HOST=imap.fastmail.com
87
- SMTP_HOST=smtp.fastmail.com
88
- SMTP_PORT=465
89
- ```
90
-
91
- ### iCloud
92
-
93
- Requires an [app-specific password](https://account.apple.com) from your Apple ID security settings.
94
-
95
- ```
96
- IMAP_HOST=imap.mail.me.com
97
- SMTP_HOST=smtp.mail.me.com
98
- SMTP_PORT=587
99
- SMTP_SECURE=false
100
- ```
101
-
102
- ### Proton Mail
103
-
104
- Proton Mail requires [Proton Mail Bridge](https://proton.me/mail/bridge) running locally; point mcp-inbox at the Bridge's advertised host/port (usually `127.0.0.1:1143` for IMAP).
105
-
106
- ---
107
-
108
- ## Troubleshooting
109
-
110
- ### "IMAP authentication failed"
111
-
112
- You're almost certainly using your account password instead of an app password. See the provider-specific links above.
113
-
114
- ### The client can't find `npx` / `spawn ENOENT`
115
-
116
- On Windows, some older clients don't resolve `.cmd` shims. Wrap the command:
11
+ **1.** Create `.mcp.json` in your project root:
117
12
 
118
13
  ```json
119
- "command": "cmd",
120
- "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]
14
+ {
15
+ "mcpServers": {
16
+ "inbox": {
17
+ "command": "npx",
18
+ "args": ["-y", "@kbzowski/mcp-inbox"],
19
+ "env": {
20
+ "IMAP_USER": "you@example.com",
21
+ "IMAP_PASSWORD": "your-app-password",
22
+ "IMAP_HOST": "imap.example.com"
23
+ }
24
+ }
25
+ }
26
+ }
121
27
  ```
122
28
 
123
- Or install globally and use the binary directly:
29
+ **2.** Add it to `.gitignore`. That file holds a password.
124
30
 
125
- ```bash
126
- npm install -g @kbzowski/mcp-inbox
127
- # then set command: "mcp-inbox" (no args)
128
- ```
129
-
130
- ### Passwords with shell-special characters
131
-
132
- If your password contains `$`, `` ` ``, `!`, or a backslash, put it in an env file / config JSON rather than passing it on a shell command line. The config files above handle this correctly; `claude mcp add --env IMAP_PASSWORD=...` works if you **single-quote** the value in your shell.
133
-
134
- ### First-run takes a while
31
+ **3.** Restart the agent. Claude Code asks once to approve project-scoped servers; `/mcp` shows whether it connected. The tools then appear as `imap_*`.
135
32
 
136
- The first `npx -y @kbzowski/mcp-inbox` invocation downloads the package. Subsequent runs are cached. If it looks hung on first boot, check your network.
33
+ On Windows, if you get `spawn ENOENT`, use `"command": "cmd", "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]`.
137
34
 
138
- ### "mcp-inbox requires Node.js 24 or later"
139
-
140
- The server requires Node 24 because `node:sqlite` (the built-in SQLite module it uses) gained its full API in Node 24. Run `node --version` to check which version your MCP client is using, and upgrade to Node 24 LTS if needed: https://nodejs.org/en/download
141
-
142
- ### Verify the connection manually
143
-
144
- From any shell, set the env vars and run:
35
+ Claude Code can also write the file for you:
145
36
 
146
37
  ```bash
147
- IMAP_USER=you@example.com IMAP_PASSWORD=... IMAP_HOST=imap.gmail.com npx -y @kbzowski/mcp-inbox
38
+ claude mcp add inbox --scope project \
39
+ --env IMAP_USER=you@example.com \
40
+ --env IMAP_PASSWORD='your-app-password' \
41
+ --env IMAP_HOST=imap.example.com \
42
+ -- npx -y @kbzowski/mcp-inbox
148
43
  ```
149
44
 
150
- On success you'll see JSON log lines on stderr: `booting mcp-inbox` and `mcp-inbox ready`. The server then idles on stdin (waiting for MCP JSON-RPC). Hit `Ctrl+C` to stop.
151
-
152
- ---
45
+ ### Other clients
153
46
 
154
- ## Tool catalog
47
+ The same `mcpServers` object works in `claude_desktop_config.json`, `~/.cursor/mcp.json` and `cline_mcp_settings.json`. VS Code reads `.vscode/mcp.json` and calls the key `servers`, not `mcpServers`. Codex CLI, Zed, Continue and Goose use their own formats: [docs/clients.md](docs/clients.md).
155
48
 
156
- All tools are prefixed `imap_` so they don't collide with other email MCPs. Every read tool accepts `response_format: "markdown" | "json"` (default markdown) and `max_staleness_seconds` (default 60 - serves from cache when fresh, syncs otherwise).
49
+ ### Credentials
157
50
 
158
- ### Discovery
51
+ Gmail, Outlook, Fastmail and iCloud all need an **app password**, not the account password.
159
52
 
160
- - **`imap_list_folders`** - list every mailbox with its path, delimiter, and RFC 6154 special-use attribute (`\Drafts`, `\Sent`, `\Trash`, `\Junk`).
161
- - **`imap_list_emails`** `(folder?, limit?, offset?, unseen_only?, since_date?, before_date?)` - paginated envelope list, newest first. Defaults to `INBOX`, 20 per page.
162
- - **`imap_search_emails`** `(folder?, subject?, from?, to?, body?, unseen?, flagged?, answered?, since_date?, before_date?)` - IMAP SEARCH on the server, returns matching envelopes from the cache. At least one criterion required. `flagged` and `answered` are three-state: `true` matches, `false` matches the negation, omitting them does not filter.
53
+ | Provider | `IMAP_HOST` | `SMTP_HOST` | `SMTP_PORT` | `SMTP_SECURE` |
54
+ |---|---|---|---|---|
55
+ | Gmail | `imap.gmail.com` | `smtp.gmail.com` | `465` | `true` |
56
+ | Outlook | `outlook.office365.com` | `smtp.office365.com` | `587` | `false` |
57
+ | Fastmail | `imap.fastmail.com` | `smtp.fastmail.com` | `465` | `true` |
58
+ | iCloud | `imap.mail.me.com` | `smtp.mail.me.com` | `587` | `false` |
59
+ | Proton | `127.0.0.1` port `1143` (Bridge) | Bridge | | |
163
60
 
164
- ### Reading
61
+ Outlook fails on the `465`/`true` defaults; both overrides are required.
165
62
 
166
- - **`imap_get_email`** `(folder, uid)` - full message: headers, plain text, HTML, and attachment metadata (filename, content type, size).
167
- - **`imap_list_drafts`** `(folder?, limit?, offset?)` - same as list_emails but auto-resolves the Drafts folder via SPECIAL-USE.
168
- - **`imap_get_draft`** `(uid, folder?)` - full draft content by UID.
169
- - **`imap_get_attachment`** `(folder, uid, filename? | part_id?, max_inline_mb?)` - download an attachment as base64 bytes, inline in the response. Memory-only, no disk cache. Default cap is 5 MB; raise via `max_inline_mb` (up to 50).
63
+ ## Tools
170
64
 
171
- ### Flagging / filing
65
+ All prefixed `imap_`. Read tools take `response_format: "markdown" | "json"` (default markdown) and `max_staleness_seconds` (default 60; serves cache when fresh, syncs otherwise). UIDs are folder-scoped, so every tool taking a `uid` also takes a `folder`.
172
66
 
173
- - **`imap_mark_read`** `(folder, uid)` - add `\Seen`. Idempotent.
174
- - **`imap_mark_unread`** `(folder, uid)` - remove `\Seen`. Idempotent.
175
- - **`imap_set_flags`** `(folder, uids, add?, remove?)` - set or clear `\Flagged` (the star / follow-up marker) and `\Answered` on up to 500 UIDs at once. Read/unread has its own tools; deleting does too, so neither `\Seen` nor `\Deleted` is accepted here.
176
- - **`imap_move_to_folder`** `(folder, uid, destination)` - IMAP MOVE with COPY+EXPUNGE fallback.
177
- - **`imap_delete_email`** `(folder, uid, hard_delete?)` - defaults to move-to-Trash. `hard_delete: true` permanently expunges.
178
-
179
- ### Composing
180
-
181
- Attachments on the composing and sending tools take `{ filename, content_base64, content_type? }`. The bytes pass through the model context, so a 2 MB PDF costs roughly 2.7M characters - to relay a file the model did not create, `imap_forward` is far cheaper.
182
-
183
- - **`imap_create_draft`** `(to, subject, body?, html?, cc?, bcc?, from?, attachments?)` - appends a new draft to the Drafts folder with the `\Draft` flag. nodemailer handles the RFC 2822 construction, so non-ASCII subjects, long bodies, and multipart text+HTML all just work.
184
- - **`imap_update_draft`** `(uid, to, subject, body?, html?, cc?, bcc?, from?, attachments?)` - replaces an existing draft. Append-then-delete: the new draft is written first, only then is the old UID removed. A failure in the middle never loses the draft.
185
-
186
- ### Sending
67
+ | Tool | Arguments |
68
+ |---|---|
69
+ | `imap_list_folders` | |
70
+ | `imap_list_emails` | `folder?, limit?, offset?, unseen_only?, since_date?, before_date?` |
71
+ | `imap_search_emails` | `folder?, subject?, from?, to?, body?, unseen?, flagged?, answered?, since_date?, before_date?, or?, not?` |
72
+ | `imap_get_email` | `folder, uid` |
73
+ | `imap_get_attachment` | `folder, uid, filename? \| part_id?, max_inline_mb?` |
74
+ | `imap_list_drafts` | `folder?, limit?, offset?` |
75
+ | `imap_get_draft` | `uid, folder?` |
76
+ | `imap_mark_read` / `imap_mark_unread` | `folder, uid` |
77
+ | `imap_set_flags` | `folder, uids, add?, remove?` |
78
+ | `imap_move_to_folder` | `folder, uid, destination` |
79
+ | `imap_delete_email` | `folder, uid, hard_delete?` |
80
+ | `imap_create_draft` | `to, subject, body?, html?, cc?, bcc?, from?, attachments?, folder?` |
81
+ | `imap_update_draft` | `uid, to, subject, body?, html?, cc?, bcc?, from?, attachments?, folder?` |
82
+ | `imap_send_email` | `to, subject, body?, html?, cc?, bcc?, from?, attachments?` |
83
+ | `imap_send_draft` | `uid, folder?` |
84
+ | `imap_reply` | `folder, uid, body?, html?, reply_all?, cc?, bcc?, from?, attachments?, mark_answered?` |
85
+ | `imap_forward` | `folder, uid, to, body?, cc?, bcc?, from?, attachments?` |
86
+
87
+ `imap_mark_read_multiple`, `imap_mark_unread_multiple`, `imap_move_multiple` and `imap_delete_multiple` take `uids` (max 500) instead of `uid`.
88
+
89
+ Worth knowing:
90
+
91
+ - `imap_get_email` returns attachment metadata only. `imap_get_attachment` fetches bytes as base64 for one response, capped at 5 MB (`max_inline_mb`, up to 50). Nothing is written to disk.
92
+ - Outgoing `attachments` are `{ filename, content_base64, content_type? }`. Those bytes cross the model context - a 2 MB PDF is roughly 2.7M characters. To pass on a file you did not create, forward it.
93
+ - `imap_forward` attaches the original verbatim as `.eml`, so its attachments, signatures and DKIM survive.
94
+ - `imap_reply` sets `\Answered` on the original (`mark_answered: false` to skip) and carries the full `References` chain.
95
+ - `imap_set_flags` writes `\Flagged` and `\Answered` only. Read state and deletion have their own tools.
96
+ - `imap_delete_email` moves to Trash; `hard_delete: true` expunges.
97
+ - `imap_update_draft` appends before deleting, so a mid-flight failure never loses the draft.
98
+
99
+ `destructiveHint` is set on move, delete, and everything that sends.
100
+
101
+ ## Environment
102
+
103
+ | Variable | Default |
104
+ |---|---|
105
+ | `IMAP_USER` `IMAP_PASSWORD` `IMAP_HOST` | required |
106
+ | `IMAP_PORT` | `993` |
107
+ | `IMAP_TLS` | `true` |
108
+ | `IMAP_TLS_REJECT_UNAUTHORIZED` | `true` |
109
+ | `IMAP_AUTH_TIMEOUT_MS` | `10000` |
110
+ | `SMTP_HOST` `SMTP_USER` `SMTP_PASSWORD` | falls back to the IMAP value |
111
+ | `SMTP_PORT` | `465` |
112
+ | `SMTP_SECURE` | `true` |
113
+ | `IMAP_CACHE_DIR` | platform cache dir |
114
+ | `IMAP_CACHE_DEFAULT_STALENESS_SEC` | `60` |
115
+ | `IMAP_CACHE_BODY_RETAIN_DAYS` | `180` (`0` keeps forever) |
116
+ | `IMAP_IDLE_ENABLED` | `true` |
117
+ | `IMAP_IDLE_FOLDERS` | `INBOX` (empty disables) |
118
+ | `DEBUG` | unset; try `mcp-inbox:*` |
119
+
120
+ Empty values count as unset. Logs go to stderr.
187
121
 
188
- - **`imap_send_email`** `(to, subject, body?, html?, cc?, bcc?, from?, attachments?)` - SMTP send + best-effort append to the Sent folder so the message shows up in the user's mail client.
189
- - **`imap_send_draft`** `(uid, folder?)` - fetches raw source of the draft, sends it exactly as written (preserves attachments and formatting), then deletes the draft.
190
- - **`imap_reply`** `(folder, uid, body?, html?, reply_all?, cc?, bcc?, from?, attachments?, mark_answered?)` - preserves threading via `In-Reply-To` / `References`. Subject gets a `Re: ` prefix. Sets `\Answered` on the original by default, so the thread reads as replied in the user's mail client.
191
- - **`imap_forward`** `(folder, uid, to, body?, cc?, bcc?, from?, attachments?)` - quotes the original inline, `Fwd: ` subject prefix, and attaches the untouched original as a `.eml` so its attachments, signatures and DKIM survive.
122
+ ## Troubleshooting
192
123
 
193
- ### Tool annotations
124
+ **"IMAP authentication failed"** - you are using the account password instead of an app password.
194
125
 
195
- Every tool carries MCP annotations so clients can gate destructive actions:
126
+ **Passwords containing `$`, `` ` ``, `!` or `\`** - put them in the config JSON, not on a command line. With `claude mcp add --env`, single-quote the value.
196
127
 
197
- | Tool | readOnly | destructive | idempotent |
198
- |---|:-:|:-:|:-:|
199
- | list_folders / list_emails / get_email / search_emails / list_drafts / get_draft / get_attachment | ✓ | | ✓ |
200
- | mark_read / mark_unread / set_flags | | | ✓ |
201
- | move_to_folder / delete_email | | ✓ | |
202
- | create_draft / update_draft | | | |
203
- | send_email / send_draft / reply / forward | | ✓ | |
128
+ **"requires Node.js 24 or later"** - `node:sqlite` needs 24. Check what your client runs, not what your shell has.
204
129
 
205
- ---
130
+ **Check it works** - `IMAP_USER=... IMAP_PASSWORD=... IMAP_HOST=... npx -y @kbzowski/mcp-inbox`. You should get `mcp-inbox ready` on stderr; it then waits on stdin.
206
131
 
207
132
  ## License
208
133
 
package/dist/app.js CHANGED
@@ -993,7 +993,7 @@ import {
993
993
  // package.json
994
994
  var package_default = {
995
995
  name: "@kbzowski/mcp-inbox",
996
- version: "0.5.0",
996
+ version: "0.5.1",
997
997
  description: "MCP server exposing IMAP/SMTP email over a fast local cache. Read, search, compose, and manage email from any IMAP provider with near-instant response times via background sync and IDLE push.",
998
998
  type: "module",
999
999
  main: "./dist/index.js",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kbzowski/mcp-inbox",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "MCP server exposing IMAP/SMTP email over a fast local cache. Read, search, compose, and manage email from any IMAP provider with near-instant response times via background sync and IDLE push.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",