@kbzowski/mcp-inbox 0.3.2 → 0.5.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
@@ -31,216 +31,24 @@ How those env vars reach the server process depends on which MCP client you use.
31
31
 
32
32
  ---
33
33
 
34
- ## Connect it to your client
34
+ ## Compatible clients
35
35
 
36
- Pick your client and follow the snippet. Each example sets `IMAP_USER`, `IMAP_PASSWORD`, and `IMAP_HOST`; add any optional variables from `.env.example` the same way.
36
+ Works with any MCP-capable client over stdio. Confirmed integrations:
37
37
 
38
- ### Claude Code (CLI)
39
-
40
- Works on macOS, Linux, and Windows.
41
-
42
- ```bash
43
- claude mcp add mcp-inbox \
44
- --env IMAP_USER=you@example.com \
45
- --env IMAP_PASSWORD=your-app-password \
46
- --env IMAP_HOST=imap.gmail.com \
47
- -- npx -y @kbzowski/mcp-inbox
48
- ```
49
-
50
- Add `-s user` (user scope) to make the server available in every project instead of just the current directory. List and verify with `claude mcp list`. Remove with `claude mcp remove mcp-inbox`.
51
-
52
- **Windows note:** works directly; Claude Code wraps `npx` correctly on Windows since mid-2025. If you hit `spawn npx ENOENT`, upgrade Claude Code first.
53
-
54
- ### Claude Desktop
55
-
56
- Config file location:
57
- - **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
58
- - **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
59
- - **Linux** (unofficial): `~/.config/Claude/claude_desktop_config.json`
60
-
61
- Edit (create the file if it doesn't exist) and merge this into the top-level object:
62
-
63
- ```json
64
- {
65
- "mcpServers": {
66
- "mcp-inbox": {
67
- "command": "npx",
68
- "args": ["-y", "@kbzowski/mcp-inbox"],
69
- "env": {
70
- "IMAP_USER": "you@example.com",
71
- "IMAP_PASSWORD": "your-app-password",
72
- "IMAP_HOST": "imap.gmail.com"
73
- }
74
- }
75
- }
76
- }
77
- ```
78
-
79
- Restart Claude Desktop after saving. The server appears in the "Search and tools" menu once the handshake completes.
80
-
81
- **Windows quirk:** if Claude Desktop fails to spawn `npx` (older Electron versions do this), replace the `command`/`args` pair with:
82
-
83
- ```json
84
- "command": "cmd",
85
- "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"],
86
- ```
87
-
88
- ### Codex CLI (OpenAI)
89
-
90
- Config lives at `~/.codex/config.toml`:
91
-
92
- ```toml
93
- [mcp_servers.mcp-inbox]
94
- command = "npx"
95
- args = ["-y", "@kbzowski/mcp-inbox"]
96
-
97
- [mcp_servers.mcp-inbox.env]
98
- IMAP_USER = "you@example.com"
99
- IMAP_PASSWORD = "your-app-password"
100
- IMAP_HOST = "imap.gmail.com"
101
- ```
102
-
103
- Verify with `codex mcp list`. If you're on Windows and Codex can't find `npx`, wrap it: `command = "cmd"`, `args = ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]`.
104
-
105
- ### Cursor
106
-
107
- **Option A - Settings UI:** Settings → MCP → Add new MCP server. Fill in:
108
- - Name: `mcp-inbox`
109
- - Type: `command`
110
- - Command: `npx -y @kbzowski/mcp-inbox`
111
- - Env: add `IMAP_USER`, `IMAP_PASSWORD`, `IMAP_HOST` one per line
112
-
113
- **Option B - edit `~/.cursor/mcp.json`:**
114
-
115
- ```json
116
- {
117
- "mcpServers": {
118
- "mcp-inbox": {
119
- "command": "npx",
120
- "args": ["-y", "@kbzowski/mcp-inbox"],
121
- "env": {
122
- "IMAP_USER": "you@example.com",
123
- "IMAP_PASSWORD": "your-app-password",
124
- "IMAP_HOST": "imap.gmail.com"
125
- }
126
- }
127
- }
128
- }
129
- ```
130
-
131
- A workspace-scoped variant goes at `.cursor/mcp.json` in the project root.
132
-
133
- ### VS Code (native MCP)
134
-
135
- VS Code added first-party MCP support in 2025. Enable it at the workspace level by creating `.vscode/mcp.json`:
136
-
137
- ```json
138
- {
139
- "servers": {
140
- "mcp-inbox": {
141
- "type": "stdio",
142
- "command": "npx",
143
- "args": ["-y", "@kbzowski/mcp-inbox"],
144
- "env": {
145
- "IMAP_USER": "you@example.com",
146
- "IMAP_PASSWORD": "your-app-password",
147
- "IMAP_HOST": "imap.gmail.com"
148
- }
149
- }
150
- }
151
- }
152
- ```
153
-
154
- User-level config: the `mcp` section under your settings JSON (`Cmd/Ctrl+Shift+P` → "Preferences: Open User Settings (JSON)").
155
-
156
- ### Cline (VS Code extension)
157
-
158
- Cline reads its MCP config from `cline_mcp_settings.json`. Open it from the Cline sidebar → MCP Servers → Configure MCP Servers. Add:
159
-
160
- ```json
161
- {
162
- "mcpServers": {
163
- "mcp-inbox": {
164
- "command": "npx",
165
- "args": ["-y", "@kbzowski/mcp-inbox"],
166
- "env": {
167
- "IMAP_USER": "you@example.com",
168
- "IMAP_PASSWORD": "your-app-password",
169
- "IMAP_HOST": "imap.gmail.com"
170
- },
171
- "disabled": false,
172
- "autoApprove": []
173
- }
174
- }
175
- }
176
- ```
177
-
178
- ### Continue.dev
179
-
180
- Edit `~/.continue/config.yaml`:
181
-
182
- ```yaml
183
- mcpServers:
184
- - name: mcp-inbox
185
- command: npx
186
- args:
187
- - "-y"
188
- - "@kbzowski/mcp-inbox"
189
- env:
190
- IMAP_USER: you@example.com
191
- IMAP_PASSWORD: your-app-password
192
- IMAP_HOST: imap.gmail.com
193
- ```
194
-
195
- ### Zed
196
-
197
- Zed's editor settings (`Cmd/Ctrl+,`) - add a `context_servers` entry:
198
-
199
- ```json
200
- {
201
- "context_servers": {
202
- "mcp-inbox": {
203
- "command": "npx",
204
- "args": ["-y", "@kbzowski/mcp-inbox"],
205
- "env": {
206
- "IMAP_USER": "you@example.com",
207
- "IMAP_PASSWORD": "your-app-password",
208
- "IMAP_HOST": "imap.gmail.com"
209
- }
210
- }
211
- }
212
- }
213
- ```
214
-
215
- ### Goose (Block)
216
-
217
- Edit `~/.config/goose/config.yaml`:
218
-
219
- ```yaml
220
- extensions:
221
- mcp-inbox:
222
- type: stdio
223
- cmd: npx
224
- args: ["-y", "@kbzowski/mcp-inbox"]
225
- envs:
226
- IMAP_USER: you@example.com
227
- IMAP_PASSWORD: your-app-password
228
- IMAP_HOST: imap.gmail.com
229
- enabled: true
230
- ```
231
-
232
- ### Any other MCP client
233
-
234
- The pattern every MCP client shares:
235
-
236
- | Field | Value |
38
+ | Client | Notes |
237
39
  |---|---|
238
- | Transport | stdio |
239
- | Command | `npx` |
240
- | Args | `["-y", "@kbzowski/mcp-inbox"]` |
241
- | Env | `IMAP_USER`, `IMAP_PASSWORD`, `IMAP_HOST` (minimum) |
242
-
243
- If the client expects a bundled executable instead of `npx`, install globally (`npm i -g @kbzowski/mcp-inbox`) and point it at `mcp-inbox` directly.
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)**.
244
52
 
245
53
  ---
246
54
 
@@ -351,7 +159,7 @@ All tools are prefixed `imap_` so they don't collide with other email MCPs. Ever
351
159
 
352
160
  - **`imap_list_folders`** - list every mailbox with its path, delimiter, and RFC 6154 special-use attribute (`\Drafts`, `\Sent`, `\Trash`, `\Junk`).
353
161
  - **`imap_list_emails`** `(folder?, limit?, offset?, unseen_only?, since_date?, before_date?)` - paginated envelope list, newest first. Defaults to `INBOX`, 20 per page.
354
- - **`imap_search_emails`** `(folder?, subject?, from?, to?, body?, unseen?, since_date?, before_date?)` - IMAP SEARCH on the server, returns matching envelopes from the cache. At least one criterion required.
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.
355
163
 
356
164
  ### Reading
357
165
 
@@ -364,20 +172,23 @@ All tools are prefixed `imap_` so they don't collide with other email MCPs. Ever
364
172
 
365
173
  - **`imap_mark_read`** `(folder, uid)` - add `\Seen`. Idempotent.
366
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.
367
176
  - **`imap_move_to_folder`** `(folder, uid, destination)` - IMAP MOVE with COPY+EXPUNGE fallback.
368
177
  - **`imap_delete_email`** `(folder, uid, hard_delete?)` - defaults to move-to-Trash. `hard_delete: true` permanently expunges.
369
178
 
370
179
  ### Composing
371
180
 
372
- - **`imap_create_draft`** `(to, subject, body?, html?, cc?, bcc?, from?)` - 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.
373
- - **`imap_update_draft`** `(uid, to, subject, body?, html?, cc?, bcc?, from?)` - 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.
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.
374
185
 
375
186
  ### Sending
376
187
 
377
- - **`imap_send_email`** `(to, subject, body?, html?, cc?, bcc?, from?)` - SMTP send + best-effort append to the Sent folder so the message shows up in the user's mail client.
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.
378
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.
379
- - **`imap_reply`** `(folder, uid, body?, html?, reply_all?, cc?, bcc?, from?)` - preserves threading via `In-Reply-To` / `References`. Subject gets a `Re: ` prefix.
380
- - **`imap_forward`** `(folder, uid, to, body?, cc?, bcc?, from?)` - quotes the original inline, `Fwd: ` subject prefix.
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.
381
192
 
382
193
  ### Tool annotations
383
194
 
@@ -386,7 +197,7 @@ Every tool carries MCP annotations so clients can gate destructive actions:
386
197
  | Tool | readOnly | destructive | idempotent |
387
198
  |---|:-:|:-:|:-:|
388
199
  | list_folders / list_emails / get_email / search_emails / list_drafts / get_draft / get_attachment | ✓ | | ✓ |
389
- | mark_read / mark_unread | | | ✓ |
200
+ | mark_read / mark_unread / set_flags | | | ✓ |
390
201
  | move_to_folder / delete_email | | ✓ | |
391
202
  | create_draft / update_draft | | | |
392
203
  | send_email / send_draft / reply / forward | | ✓ | |