@kbzowski/mcp-inbox 0.5.0 → 0.6.0

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.
package/README.md CHANGED
@@ -1,208 +1,219 @@
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
11
+ **1.** Create `.mcp.json` in your project root:
12
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
13
+ ```json
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
+ }
26
27
  ```
27
28
 
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
- ---
29
+ **2.** Add it to `.gitignore`. That file holds a password.
54
30
 
55
- ## Provider notes
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_*`.
56
32
 
57
- ### Gmail / Google Workspace
33
+ On Windows, if you get `spawn ENOENT`, use `"command": "cmd", "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]`.
58
34
 
59
- Use an **[app password](https://myaccount.google.com/apppasswords)**, not your account password. Requires 2-Step Verification turned on first.
35
+ Claude Code can also write the file for you:
60
36
 
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
37
+ ```bash
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
67
43
  ```
68
44
 
69
- ### Outlook / Microsoft 365
45
+ ### Other clients
70
46
 
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.
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).
80
48
 
81
- ### Fastmail
49
+ ### Docker
82
50
 
83
- Use an [app password](https://app.fastmail.com/settings/security/devicekeys/add) (account-level passwords are rejected).
51
+ No Node on the host? Build the image and let the agent run it. The server talks over stdio, so the container needs `-i` (and no `-t`).
84
52
 
53
+ ```bash
54
+ docker build -t mcp-inbox .
85
55
  ```
86
- IMAP_HOST=imap.fastmail.com
87
- SMTP_HOST=smtp.fastmail.com
88
- SMTP_PORT=465
89
- ```
90
-
91
- ### iCloud
92
56
 
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
57
+ ```json
58
+ {
59
+ "mcpServers": {
60
+ "inbox": {
61
+ "command": "docker",
62
+ "args": [
63
+ "run", "-i", "--rm",
64
+ "-v", "mcp-inbox-cache:/data",
65
+ "-e", "IMAP_USER", "-e", "IMAP_PASSWORD", "-e", "IMAP_HOST",
66
+ "mcp-inbox"
67
+ ],
68
+ "env": {
69
+ "IMAP_USER": "you@example.com",
70
+ "IMAP_PASSWORD": "your-app-password",
71
+ "IMAP_HOST": "imap.example.com"
72
+ }
73
+ }
74
+ }
75
+ }
100
76
  ```
101
77
 
102
- ### Proton Mail
78
+ The `mcp-inbox-cache` volume keeps the SQLite cache between runs; without it every start re-syncs from scratch. Pass any other variable from [Environment](#environment) the same way (`-e NAME`).
103
79
 
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
80
+ ### Shared server (streamable HTTP)
109
81
 
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:
82
+ To connect several clients to one server, run it over HTTP instead of stdio. Set `MCP_HTTP_PORT` and `MCP_AUTH_TOKEN` (16+ characters; required, because this exposes your mailbox). Put both in `.env` and run `docker compose up -d`; `compose.yaml` publishes `127.0.0.1:3000`. Without Docker: `MCP_HTTP_PORT=3000 MCP_AUTH_TOKEN=... npx -y @kbzowski/mcp-inbox`.
117
83
 
118
84
  ```json
119
- "command": "cmd",
120
- "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]
85
+ {
86
+ "mcpServers": {
87
+ "inbox": {
88
+ "type": "http",
89
+ "url": "http://localhost:3000/mcp",
90
+ "headers": { "Authorization": "Bearer your-token" }
91
+ }
92
+ }
93
+ }
121
94
  ```
122
95
 
123
- Or install globally and use the binary directly:
96
+ Claude Code: `claude mcp add --transport http inbox http://localhost:3000/mcp --header "Authorization: Bearer your-token"`. The server is stateless and shares one IMAP connection and cache across clients. There is no TLS; keep it on localhost or put a reverse proxy in front.
124
97
 
125
- ```bash
126
- npm install -g @kbzowski/mcp-inbox
127
- # then set command: "mcp-inbox" (no args)
128
- ```
98
+ The image is Debian-based on purpose: `sqlite-vec` (semantic search) has no Alpine build. If your embeddings server runs on the host, use `host.docker.internal` instead of `localhost` in `IMAP_EMBEDDINGS_BASE_URL`.
129
99
 
130
- ### Passwords with shell-special characters
100
+ ### Credentials
131
101
 
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.
102
+ Gmail, Outlook, Fastmail and iCloud all need an **app password**, not the account password.
133
103
 
134
- ### First-run takes a while
104
+ | Provider | `IMAP_HOST` | `SMTP_HOST` | `SMTP_PORT` | `SMTP_SECURE` |
105
+ |---|---|---|---|---|
106
+ | Gmail | `imap.gmail.com` | `smtp.gmail.com` | `465` | `true` |
107
+ | Outlook | `outlook.office365.com` | `smtp.office365.com` | `587` | `false` |
108
+ | Fastmail | `imap.fastmail.com` | `smtp.fastmail.com` | `465` | `true` |
109
+ | iCloud | `imap.mail.me.com` | `smtp.mail.me.com` | `587` | `false` |
110
+ | Proton | `127.0.0.1` port `1143` (Bridge) | Bridge | | |
135
111
 
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.
112
+ Outlook fails on the `465`/`true` defaults; both overrides are required.
137
113
 
138
- ### "mcp-inbox requires Node.js 24 or later"
114
+ ## Tools
139
115
 
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
116
+ 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`.
141
117
 
142
- ### Verify the connection manually
143
-
144
- From any shell, set the env vars and run:
118
+ | Tool | Arguments |
119
+ |---|---|
120
+ | `imap_list_folders` | |
121
+ | `imap_list_emails` | `folder?, limit?, offset?, unseen_only?, since_date?, before_date?` |
122
+ | `imap_search_emails` | `folder?, subject?, from?, to?, body?, unseen?, flagged?, answered?, since_date?, before_date?, or?, not?` |
123
+ | `imap_semantic_search` | `query, folder?, limit?, since_date?, before_date?` |
124
+ | `imap_index_folder` | `folders?, max_messages?` |
125
+ | `imap_get_email` | `folder, uid` |
126
+ | `imap_get_attachment` | `folder, uid, filename? \| part_id?, max_inline_mb?` |
127
+ | `imap_list_drafts` | `folder?, limit?, offset?` |
128
+ | `imap_get_draft` | `uid, folder?` |
129
+ | `imap_mark_read` / `imap_mark_unread` | `folder, uid` |
130
+ | `imap_set_flags` | `folder, uids, add?, remove?` |
131
+ | `imap_move_to_folder` | `folder, uid, destination` |
132
+ | `imap_delete_email` | `folder, uid, hard_delete?` |
133
+ | `imap_create_draft` | `to, subject, body?, html?, cc?, bcc?, from?, attachments?, folder?` |
134
+ | `imap_update_draft` | `uid, to, subject, body?, html?, cc?, bcc?, from?, attachments?, folder?` |
135
+ | `imap_send_email` | `to, subject, body?, html?, cc?, bcc?, from?, attachments?` |
136
+ | `imap_send_draft` | `uid, folder?` |
137
+ | `imap_reply` | `folder, uid, body?, html?, reply_all?, cc?, bcc?, from?, attachments?, mark_answered?` |
138
+ | `imap_forward` | `folder, uid, to, body?, cc?, bcc?, from?, attachments?` |
139
+
140
+ `imap_mark_read_multiple`, `imap_mark_unread_multiple`, `imap_move_multiple` and `imap_delete_multiple` take `uids` (max 500) instead of `uid`.
141
+
142
+ Worth knowing:
143
+
144
+ - `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.
145
+ - 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.
146
+ - `imap_forward` attaches the original verbatim as `.eml`, so its attachments, signatures and DKIM survive.
147
+ - `imap_reply` sets `\Answered` on the original (`mark_answered: false` to skip) and carries the full `References` chain.
148
+ - `imap_set_flags` writes `\Flagged` and `\Answered` only. Read state and deletion have their own tools.
149
+ - `imap_delete_email` moves to Trash; `hard_delete: true` expunges.
150
+ - `imap_update_draft` appends before deleting, so a mid-flight failure never loses the draft.
151
+
152
+ `destructiveHint` is set on move, delete, and everything that sends.
153
+
154
+ ## Semantic search (optional)
155
+
156
+ `imap_search_emails` matches literal text on the server. `imap_semantic_search` matches meaning: "the invoice from the hosting provider" finds a message titled "Payment receipt #4417". It works across languages and paraphrases, and it only ranks what has been indexed.
157
+
158
+ Indexing covers the subject, the sender, and the message text, so a message is findable by what it says even when its subject is useless ("Re: 4417"). Quoted reply history is stripped before embedding, and a message is ranked by its single most relevant passage.
159
+
160
+ Off unless you set `IMAP_EMBEDDINGS_BASE_URL`. Any OpenAI-compatible `/v1/embeddings` endpoint works, including a local one:
145
161
 
146
162
  ```bash
147
- IMAP_USER=you@example.com IMAP_PASSWORD=... IMAP_HOST=imap.gmail.com npx -y @kbzowski/mcp-inbox
163
+ IMAP_EMBEDDINGS_BASE_URL=https://your-endpoint/v1
164
+ IMAP_EMBEDDINGS_API_KEY=sk-...
148
165
  ```
149
166
 
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
- ---
153
-
154
- ## Tool catalog
155
-
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).
167
+ **Indexing is opt-in per folder.** Run `imap_index_folder` on the folders you care about before searching them - it takes a list, and they share the call's `max_messages` budget. That call sends each message's subject, sender, and body text to the configured endpoint. **Attachments are never downloaded or sent** - only the message's text part is fetched, which on a real mailbox is roughly 80x less data than the full messages. It is safe to re-run: already-indexed messages are skipped, so a large folder can be indexed over several calls. Afterwards a background pass keeps every indexed folder current, so new mail becomes searchable on its own. It runs every `IMAP_EMBEDDINGS_SWEEP_MINUTES` (15 by default, `0` disables it) and embeds at most `IMAP_EMBEDDINGS_SWEEP_BATCH` messages per pass. Searching never writes, so its latency stays predictable; `pending_index` tells you when the index is still catching up.
157
168
 
158
- ### Discovery
169
+ `imap_semantic_search` takes an optional `folder`. Omit it and every indexed folder is searched in one pass, with each result reporting the folder it came from.
159
170
 
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.
171
+ If your IMAP server refuses to serve individual body parts, indexing falls back to subjects and senders alone and says so: `bodies_indexed` comes back as zero.
163
172
 
164
- ### Reading
173
+ Vectors live in the same SQLite cache as everything else and survive restarts. They also outlive the message bodies that `IMAP_CACHE_BODY_RETAIN_DAYS` prunes, so old mail stays findable.
165
174
 
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).
175
+ Changing `IMAP_EMBEDDINGS_MODEL` or `IMAP_EMBEDDINGS_DIMS` drops the index - the vector table's dimensionality is fixed when it is created. Upgrading mcp-inbox can do the same when the index format changes. Either way the fix is the same: re-run `imap_index_folder`.
170
176
 
171
- ### Flagging / filing
177
+ **Platform support.** Vector search needs the `sqlite-vec` extension, which ships prebuilt binaries for linux-x64/arm64, macOS x64/arm64, and windows-x64. On **windows-arm64 and Alpine/musl** there is no binary: the two semantic tools return a clear error pointing at `imap_search_emails`, and every other tool works normally.
172
178
 
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.
179
+ ## Environment
178
180
 
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
181
+ | Variable | Default |
182
+ |---|---|
183
+ | `IMAP_USER` `IMAP_PASSWORD` `IMAP_HOST` | required |
184
+ | `IMAP_PORT` | `993` |
185
+ | `IMAP_TLS` | `true` |
186
+ | `IMAP_TLS_REJECT_UNAUTHORIZED` | `true` |
187
+ | `IMAP_AUTH_TIMEOUT_MS` | `10000` |
188
+ | `SMTP_HOST` `SMTP_USER` `SMTP_PASSWORD` | falls back to the IMAP value |
189
+ | `SMTP_PORT` | `465` |
190
+ | `SMTP_SECURE` | `true` |
191
+ | `IMAP_CACHE_DIR` | platform cache dir |
192
+ | `IMAP_CACHE_DEFAULT_STALENESS_SEC` | `60` |
193
+ | `IMAP_CACHE_BODY_RETAIN_DAYS` | `180` (`0` keeps forever) |
194
+ | `IMAP_EMBEDDINGS_BASE_URL` | unset (semantic search off) |
195
+ | `IMAP_EMBEDDINGS_API_KEY` | unset (no auth header sent) |
196
+ | `IMAP_EMBEDDINGS_MODEL` | `arctic-embed-l-v2` |
197
+ | `IMAP_EMBEDDINGS_DIMS` | `1024` |
198
+ | `IMAP_EMBEDDINGS_BATCH_SIZE` | `64` |
199
+ | `IMAP_EMBEDDINGS_TIMEOUT_MS` | `30000` |
200
+ | `IMAP_EMBEDDINGS_SWEEP_MINUTES` | `15` (`0` disables background indexing) |
201
+ | `IMAP_EMBEDDINGS_SWEEP_BATCH` | `200` |
202
+ | `IMAP_IDLE_ENABLED` | `true` |
203
+ | `IMAP_IDLE_FOLDERS` | `INBOX` (empty disables) |
204
+ | `DEBUG` | unset; try `mcp-inbox:*` |
205
+
206
+ Empty values count as unset. Logs go to stderr.
187
207
 
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.
208
+ ## Troubleshooting
192
209
 
193
- ### Tool annotations
210
+ **"IMAP authentication failed"** - you are using the account password instead of an app password.
194
211
 
195
- Every tool carries MCP annotations so clients can gate destructive actions:
212
+ **Passwords containing `$`, `` ` ``, `!` or `\`** - put them in the config JSON, not on a command line. With `claude mcp add --env`, single-quote the value.
196
213
 
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 | | ✓ | |
214
+ **"requires Node.js 24 or later"** - `node:sqlite` needs 24. Check what your client runs, not what your shell has.
204
215
 
205
- ---
216
+ **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
217
 
207
218
  ## License
208
219