@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 +163 -152
- package/dist/app.js +1382 -312
- package/dist/cache/backfill.d.ts +35 -0
- package/dist/cache/db.d.ts +6 -0
- package/dist/cache/indexer.d.ts +34 -0
- package/dist/cache/queries.d.ts +18 -0
- package/dist/cache/schema.d.ts +114 -0
- package/dist/cache/vectors.d.ts +77 -0
- package/dist/config/env.d.ts +38 -0
- package/dist/embeddings/chunk.d.ts +3 -0
- package/dist/embeddings/client.d.ts +11 -0
- package/dist/errors/types.d.ts +3 -1
- package/dist/formatters/markdown.d.ts +23 -0
- package/dist/http.d.ts +14 -0
- package/dist/imap/body-text.d.ts +47 -0
- package/dist/migrations/20260804153609_illegal_scream/migration.sql +8 -0
- package/dist/migrations/20260804153609_illegal_scream/snapshot.json +383 -0
- package/dist/tools/define-tool.d.ts +4 -0
- package/dist/tools/emails/index-folder.d.ts +10 -0
- package/dist/tools/emails/semantic-search.d.ts +13 -0
- package/dist/tools/emails/shared.d.ts +7 -0
- package/package.json +18 -18
package/README.md
CHANGED
|
@@ -1,208 +1,219 @@
|
|
|
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
|
-
|
|
11
|
+
**1.** Create `.mcp.json` in your project root:
|
|
12
12
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
33
|
+
On Windows, if you get `spawn ENOENT`, use `"command": "cmd", "args": ["/c", "npx", "-y", "@kbzowski/mcp-inbox"]`.
|
|
58
34
|
|
|
59
|
-
|
|
35
|
+
Claude Code can also write the file for you:
|
|
60
36
|
|
|
61
|
-
```
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
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
|
-
###
|
|
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
|
-
###
|
|
49
|
+
### Docker
|
|
82
50
|
|
|
83
|
-
|
|
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
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
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
|
-
|
|
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
|
-
|
|
105
|
-
|
|
106
|
-
---
|
|
107
|
-
|
|
108
|
-
## Troubleshooting
|
|
80
|
+
### Shared server (streamable HTTP)
|
|
109
81
|
|
|
110
|
-
|
|
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
|
-
|
|
120
|
-
"
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
###
|
|
100
|
+
### Credentials
|
|
131
101
|
|
|
132
|
-
|
|
102
|
+
Gmail, Outlook, Fastmail and iCloud all need an **app password**, not the account password.
|
|
133
103
|
|
|
134
|
-
|
|
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
|
-
|
|
112
|
+
Outlook fails on the `465`/`true` defaults; both overrides are required.
|
|
137
113
|
|
|
138
|
-
|
|
114
|
+
## Tools
|
|
139
115
|
|
|
140
|
-
|
|
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
|
-
|
|
143
|
-
|
|
144
|
-
|
|
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
|
-
|
|
163
|
+
IMAP_EMBEDDINGS_BASE_URL=https://your-endpoint/v1
|
|
164
|
+
IMAP_EMBEDDINGS_API_KEY=sk-...
|
|
148
165
|
```
|
|
149
166
|
|
|
150
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
180
|
-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
|
|
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
|
-
|
|
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
|
-
|
|
210
|
+
**"IMAP authentication failed"** - you are using the account password instead of an app password.
|
|
194
211
|
|
|
195
|
-
|
|
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
|
-
|
|
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
|
|