@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 +25 -214
- package/dist/app.js +784 -376
- package/dist/cache/queries.d.ts +33 -4
- package/dist/cache/schema.d.ts +24 -2
- package/dist/cache/sync.d.ts +24 -7
- package/dist/config/env.d.ts +15 -27
- package/dist/imap/client.d.ts +9 -1
- package/dist/imap/mime-builder.d.ts +12 -0
- package/dist/imap/search.d.ts +6 -0
- package/dist/index.js +0 -1
- package/dist/migrations/20260804112339_fantastic_miss_america/migration.sql +1 -0
- package/dist/migrations/20260804112339_fantastic_miss_america/snapshot.json +310 -0
- package/dist/tools/compose-schema.d.ts +14 -0
- package/dist/tools/drafts/create-draft.d.ts +5 -0
- package/dist/tools/drafts/get-draft.d.ts +1 -1
- package/dist/tools/drafts/list-drafts.d.ts +1 -1
- package/dist/tools/drafts/update-draft.d.ts +5 -0
- package/dist/tools/emails/flags.d.ts +15 -0
- package/dist/tools/emails/get-email.d.ts +1 -1
- package/dist/tools/emails/list-emails.d.ts +1 -1
- package/dist/tools/emails/search-emails.d.ts +3 -1
- package/dist/tools/emails/set-flags.d.ts +13 -0
- package/dist/tools/emails/shared.d.ts +25 -27
- package/dist/tools/send/forward.d.ts +7 -1
- package/dist/tools/send/reply.d.ts +14 -1
- package/dist/tools/send/send-email.d.ts +5 -0
- package/package.json +14 -13
- package/dist/app.js.map +0 -7
- package/dist/index.js.map +0 -7
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
|
-
##
|
|
34
|
+
## Compatible clients
|
|
35
35
|
|
|
36
|
-
|
|
36
|
+
Works with any MCP-capable client over stdio. Confirmed integrations:
|
|
37
37
|
|
|
38
|
-
|
|
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
|
-
|
|
|
239
|
-
|
|
|
240
|
-
|
|
|
241
|
-
|
|
|
242
|
-
|
|
243
|
-
|
|
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
|
-
|
|
373
|
-
|
|
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 | | ✓ | |
|