@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.
- package/README.md +100 -175
- package/dist/app.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,208 +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
|
-
## 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
|
-
|
|
120
|
-
"
|
|
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
|
-
|
|
29
|
+
**2.** Add it to `.gitignore`. That file holds a password.
|
|
124
30
|
|
|
125
|
-
|
|
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
|
-
|
|
33
|
+
On Windows, if you get `spawn ENOENT`, use `"command": "cmd", "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]`.
|
|
137
34
|
|
|
138
|
-
|
|
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
|
-
|
|
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
|
-
|
|
151
|
-
|
|
152
|
-
---
|
|
45
|
+
### Other clients
|
|
153
46
|
|
|
154
|
-
|
|
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
|
-
|
|
49
|
+
### Credentials
|
|
157
50
|
|
|
158
|
-
|
|
51
|
+
Gmail, Outlook, Fastmail and iCloud all need an **app password**, not the account password.
|
|
159
52
|
|
|
160
|
-
|
|
161
|
-
|
|
162
|
-
|
|
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
|
-
|
|
61
|
+
Outlook fails on the `465`/`true` defaults; both overrides are required.
|
|
165
62
|
|
|
166
|
-
|
|
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
|
-
|
|
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
|
-
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
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
|
-
|
|
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
|
-
|
|
124
|
+
**"IMAP authentication failed"** - you are using the account password instead of an app password.
|
|
194
125
|
|
|
195
|
-
|
|
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
|
-
|
|
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.
|
|
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.
|
|
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",
|