@kbzowski/mcp-inbox 0.4.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.
- package/README.md +88 -352
- package/dist/app.js +774 -398
- package/dist/cache/queries.d.ts +25 -3
- package/dist/cache/schema.d.ts +24 -2
- package/dist/cache/sync.d.ts +16 -6
- 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 +12 -13
- package/dist/app.js.map +0 -7
- package/dist/index.js.map +0 -7
package/README.md
CHANGED
|
@@ -1,397 +1,133 @@
|
|
|
1
1
|
# mcp-inbox
|
|
2
2
|
|
|
3
|
-
|
|
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
|
|
5
|
+
Works with any IMAP provider - Gmail, Outlook, Fastmail, iCloud, Proton (via Bridge), Dovecot, Exchange.
|
|
6
6
|
|
|
7
|
-
|
|
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
|
-
|
|
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
|
-
## Connect it to your client
|
|
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.
|
|
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:
|
|
11
|
+
**1.** Create `.mcp.json` in your project root:
|
|
62
12
|
|
|
63
13
|
```json
|
|
64
14
|
{
|
|
65
15
|
"mcpServers": {
|
|
66
|
-
"
|
|
16
|
+
"inbox": {
|
|
67
17
|
"command": "npx",
|
|
68
18
|
"args": ["-y", "@kbzowski/mcp-inbox"],
|
|
69
19
|
"env": {
|
|
70
20
|
"IMAP_USER": "you@example.com",
|
|
71
21
|
"IMAP_PASSWORD": "your-app-password",
|
|
72
|
-
"IMAP_HOST": "imap.
|
|
22
|
+
"IMAP_HOST": "imap.example.com"
|
|
73
23
|
}
|
|
74
24
|
}
|
|
75
25
|
}
|
|
76
26
|
}
|
|
77
27
|
```
|
|
78
28
|
|
|
79
|
-
|
|
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"]`.
|
|
29
|
+
**2.** Add it to `.gitignore`. That file holds a password.
|
|
104
30
|
|
|
105
|
-
|
|
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_*`.
|
|
106
32
|
|
|
107
|
-
|
|
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
|
|
33
|
+
On Windows, if you get `spawn ENOENT`, use `"command": "cmd", "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]`.
|
|
112
34
|
|
|
113
|
-
|
|
35
|
+
Claude Code can also write the file for you:
|
|
114
36
|
|
|
115
|
-
```
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
"env": {
|
|
122
|
-
"IMAP_USER": "you@example.com",
|
|
123
|
-
"IMAP_PASSWORD": "your-app-password",
|
|
124
|
-
"IMAP_HOST": "imap.gmail.com"
|
|
125
|
-
}
|
|
126
|
-
}
|
|
127
|
-
}
|
|
128
|
-
}
|
|
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
|
|
129
43
|
```
|
|
130
44
|
|
|
131
|
-
|
|
45
|
+
### Other clients
|
|
132
46
|
|
|
133
|
-
|
|
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).
|
|
134
48
|
|
|
135
|
-
|
|
49
|
+
### Credentials
|
|
136
50
|
|
|
137
|
-
|
|
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
|
-
```
|
|
51
|
+
Gmail, Outlook, Fastmail and iCloud all need an **app password**, not the account password.
|
|
153
52
|
|
|
154
|
-
|
|
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 | | |
|
|
155
60
|
|
|
156
|
-
|
|
61
|
+
Outlook fails on the `465`/`true` defaults; both overrides are required.
|
|
157
62
|
|
|
158
|
-
|
|
63
|
+
## Tools
|
|
159
64
|
|
|
160
|
-
|
|
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
|
-
```
|
|
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`.
|
|
194
66
|
|
|
195
|
-
|
|
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 |
|
|
67
|
+
| Tool | Arguments |
|
|
237
68
|
|---|---|
|
|
238
|
-
|
|
|
239
|
-
|
|
|
240
|
-
|
|
|
241
|
-
|
|
|
242
|
-
|
|
243
|
-
|
|
244
|
-
|
|
245
|
-
|
|
246
|
-
|
|
247
|
-
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
258
|
-
|
|
259
|
-
|
|
260
|
-
|
|
261
|
-
|
|
262
|
-
|
|
263
|
-
|
|
264
|
-
|
|
265
|
-
|
|
266
|
-
|
|
267
|
-
|
|
268
|
-
|
|
269
|
-
|
|
270
|
-
|
|
271
|
-
|
|
272
|
-
|
|
273
|
-
|
|
274
|
-
|
|
275
|
-
|
|
276
|
-
|
|
277
|
-
|
|
278
|
-
|
|
279
|
-
SMTP_HOST
|
|
280
|
-
SMTP_PORT
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
288
|
-
|
|
289
|
-
|
|
290
|
-
SMTP_PORT=587
|
|
291
|
-
SMTP_SECURE=false
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
### Proton Mail
|
|
295
|
-
|
|
296
|
-
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).
|
|
297
|
-
|
|
298
|
-
---
|
|
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.
|
|
299
121
|
|
|
300
122
|
## Troubleshooting
|
|
301
123
|
|
|
302
|
-
|
|
303
|
-
|
|
304
|
-
You're almost certainly using your account password instead of an app password. See the provider-specific links above.
|
|
305
|
-
|
|
306
|
-
### The client can't find `npx` / `spawn ENOENT`
|
|
307
|
-
|
|
308
|
-
On Windows, some older clients don't resolve `.cmd` shims. Wrap the command:
|
|
309
|
-
|
|
310
|
-
```json
|
|
311
|
-
"command": "cmd",
|
|
312
|
-
"args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]
|
|
313
|
-
```
|
|
314
|
-
|
|
315
|
-
Or install globally and use the binary directly:
|
|
316
|
-
|
|
317
|
-
```bash
|
|
318
|
-
npm install -g @kbzowski/mcp-inbox
|
|
319
|
-
# then set command: "mcp-inbox" (no args)
|
|
320
|
-
```
|
|
321
|
-
|
|
322
|
-
### Passwords with shell-special characters
|
|
323
|
-
|
|
324
|
-
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.
|
|
325
|
-
|
|
326
|
-
### First-run takes a while
|
|
327
|
-
|
|
328
|
-
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.
|
|
329
|
-
|
|
330
|
-
### "mcp-inbox requires Node.js 24 or later"
|
|
331
|
-
|
|
332
|
-
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
|
|
333
|
-
|
|
334
|
-
### Verify the connection manually
|
|
335
|
-
|
|
336
|
-
From any shell, set the env vars and run:
|
|
337
|
-
|
|
338
|
-
```bash
|
|
339
|
-
IMAP_USER=you@example.com IMAP_PASSWORD=... IMAP_HOST=imap.gmail.com npx -y @kbzowski/mcp-inbox
|
|
340
|
-
```
|
|
341
|
-
|
|
342
|
-
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.
|
|
343
|
-
|
|
344
|
-
---
|
|
345
|
-
|
|
346
|
-
## Tool catalog
|
|
347
|
-
|
|
348
|
-
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).
|
|
349
|
-
|
|
350
|
-
### Discovery
|
|
351
|
-
|
|
352
|
-
- **`imap_list_folders`** - list every mailbox with its path, delimiter, and RFC 6154 special-use attribute (`\Drafts`, `\Sent`, `\Trash`, `\Junk`).
|
|
353
|
-
- **`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.
|
|
355
|
-
|
|
356
|
-
### Reading
|
|
357
|
-
|
|
358
|
-
- **`imap_get_email`** `(folder, uid)` - full message: headers, plain text, HTML, and attachment metadata (filename, content type, size).
|
|
359
|
-
- **`imap_list_drafts`** `(folder?, limit?, offset?)` - same as list_emails but auto-resolves the Drafts folder via SPECIAL-USE.
|
|
360
|
-
- **`imap_get_draft`** `(uid, folder?)` - full draft content by UID.
|
|
361
|
-
- **`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).
|
|
362
|
-
|
|
363
|
-
### Flagging / filing
|
|
364
|
-
|
|
365
|
-
- **`imap_mark_read`** `(folder, uid)` - add `\Seen`. Idempotent.
|
|
366
|
-
- **`imap_mark_unread`** `(folder, uid)` - remove `\Seen`. Idempotent.
|
|
367
|
-
- **`imap_move_to_folder`** `(folder, uid, destination)` - IMAP MOVE with COPY+EXPUNGE fallback.
|
|
368
|
-
- **`imap_delete_email`** `(folder, uid, hard_delete?)` - defaults to move-to-Trash. `hard_delete: true` permanently expunges.
|
|
369
|
-
|
|
370
|
-
### Composing
|
|
371
|
-
|
|
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.
|
|
374
|
-
|
|
375
|
-
### Sending
|
|
376
|
-
|
|
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.
|
|
378
|
-
- **`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.
|
|
381
|
-
|
|
382
|
-
### Tool annotations
|
|
124
|
+
**"IMAP authentication failed"** - you are using the account password instead of an app password.
|
|
383
125
|
|
|
384
|
-
|
|
126
|
+
**Passwords containing `$`, `` ` ``, `!` or `\`** - put them in the config JSON, not on a command line. With `claude mcp add --env`, single-quote the value.
|
|
385
127
|
|
|
386
|
-
|
|
387
|
-
|---|:-:|:-:|:-:|
|
|
388
|
-
| list_folders / list_emails / get_email / search_emails / list_drafts / get_draft / get_attachment | ✓ | | ✓ |
|
|
389
|
-
| mark_read / mark_unread | | | ✓ |
|
|
390
|
-
| move_to_folder / delete_email | | ✓ | |
|
|
391
|
-
| create_draft / update_draft | | | |
|
|
392
|
-
| 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.
|
|
393
129
|
|
|
394
|
-
|
|
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.
|
|
395
131
|
|
|
396
132
|
## License
|
|
397
133
|
|