# io.github.csitte/mailwarden (npm · mailwarden)

Native Gmail MCP server: search, labels, archive, trash, attachments, and snooze.

- Trust score: 29/100 (low)
- Change this week: +5
- Registry status: active
- Liveness: live
- Owner verified: no
- Last scored: 2026-08-03

## Components

- npm · `mailwarden`: 29/100 (this document), [markdown](https://verifymcp.io/servers/csitte-mailwarden/mailwarden.md), [page](https://verifymcp.io/servers/csitte-mailwarden/mailwarden)

## Channel facts

- Registry: `npm`
- Package: `mailwarden`
- Version: `0.3.0`
- Transport: `stdio`

## Trust breakdown

How this component scores in each security and reliability category. Every signal is checked automatically from public evidence about the published package, including repeated runs of it in an isolated sandbox, and we only credit what we can confirm. Scores are 0–100 per category. Scoring method: https://verifymcp.io/docs/scoring (what has changed: https://verifymcp.io/docs/scoring/changelog)

Scored 2026-08-03.

- **Supply Chain Security**: 31/100
  - Malware scan not yet available for this package.
  - CVE check failed: a known high-severity CVE affects uuid 9.0.1, reached via google-auth-library > gaxios > uuid. A fixed version is available.
  - No install/post-install scripts declared.
  - Only part of the dependency tree could be resolved (152 of 154), so this covers what we could see, not the whole tree.
- **Provenance & Transparency**: 97/100
  - Source repository is publicly reachable at the declared URL.
  - Cryptographically verified build provenance (signed, bound to csitte/mailwarden).
  - Clear OSI-approved license (MIT).
  - Actively maintained (last published 0 days ago).
  - Disclosure check failed: no security disclosure policy was found in the source repository.
- **Schema Quality & AI Usability**: 0/100
  - Schema quality not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- **Stability & Change Management**: 0/100
  - Stability not yet verified: we do not have a sandbox capture of the MCP schema this version of the package serves yet.
- **Tool Coverage**: 0/100
  - Tool coverage not yet verified: we do not have a sandbox capture of the tool definitions this version of the package serves yet.
- **Capabilities**: 0/100
  - Protocol version not yet verified: we do not have a sandbox capture of the MCP handshake this version of the package performs yet.

**Unverified: 4 categories.** Categories scored 0 because our sandbox run of this package has not given us the schema these checks need to read. That is a gap on our side rather than a finding about the package, and we only credit what we can confirm, so the score stands at 0 until the capture succeeds. We are working through the fleet, so this normally clears without any action from you.

## Install

### Claude

```bash
claude mcp add csitte-mailwarden -- npx -y mailwarden
```

### Codex

```bash
codex mcp add csitte-mailwarden -- npx -y mailwarden
```

### opencode

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "csitte-mailwarden": {
      "type": "local",
      "command": [
        "npx",
        "-y",
        "mailwarden"
      ],
      "enabled": true
    }
  }
}
```

### OpenClaw

```bash
openclaw mcp add csitte-mailwarden --command npx --arg -y --arg mailwarden
```

### Hermes

```yaml
mcp_servers:
  csitte-mailwarden:
    command: "npx"
    args: ["-y", "mailwarden"]
```

### Other

```json
{
  "mcpServers": {
    "csitte-mailwarden": {
      "command": "npx",
      "args": [
        "-y",
        "mailwarden"
      ]
    }
  }
}
```

## Changelog

Every change recorded for this component, newest first. Days that predate change tracking, or that we cannot explain, say so: "we were watching and nothing happened" and "we were not watching" are different claims.

### 2026-08-03 (score 29, −49)

- [security regression] Stability: 0.23 → unverified
- [security regression] Malware scan: pass → unverified
- [functional regression] Tool coverage: 100 → unverified
- [functional regression] Capabilities: pass → unverified
- [functional] Package version: 0.2.0 → 0.3.0

### 2026-08-02 (score 78, +60)

- [security regression] CVE-2026-41907 affects this package: high
- [security regression] Known CVEs: unverified → fail
- [security improvement] Install scripts: unverified → pass
- [security improvement] Provenance: unverified → pass
- [security improvement] Malware scan: unverified → pass
- [security] The attested source repository moved: csitte/mailwarden
- [functional regression] Tool coverage: 100 → unverified
- [functional improvement] License: unverified → pass
- [functional improvement] Schema quality: unverified → excellent
- [functional improvement] Dependency health: unverified → partial
- [functional improvement] Maintenance: unverified → pass
- [functional improvement] MCP protocol: unverified → pass
- [functional improvement] Stability: unverified → 0.23
- [functional] Licence: MIT
- [functional] Package version: 0.1.10 → 0.2.0

### 2026-08-01 (score 18, +12)

- [functional] We updated how we score, so this day's move reflects our rubric, not a change to the server

### 2026-07-31 (score 6, −18)

- [functional regression] Tool coverage: 100 → unverified
- [functional] First check of Schema quality: unverified

### 2026-07-27 (score 24)

First indexed and scored.

## MCP tools (15)

### `search` (~147 tokens)

Search Gmail with native query syntax (e.g. 'in:inbox from:foo@bar.com newer_than:7d'). Returns thread summaries; read-state/category predicates are re-verified against each hit's live labels. Paginated: when more results exist, the response carries a nextPageToken — pass it back via pageToken to fetch the next page. USE WHEN: locating threads by sender, subject, date, label, or read state. DO NOT USE: to fetch a thread you already have the ID of (use get_thread). SIDE EFFECTS: none.

Input parameters:

- `maxResults` (integer)
- `pageToken` (string)
- `query` (string, required)

Output parameters:

- `nextPageToken` (string)
- `threads` (array)

### `get_thread` (~81 tokens)

Fetch a full thread by ID: headers, plaintext + HTML bodies, and attachment metadata. USE WHEN: reading a thread's content after finding it via search. DO NOT USE: with a message ID — this takes thread IDs. SIDE EFFECTS: none (does not mark as read).

Input parameters:

- `full` (boolean)
- `threadId` (string, required)

Output parameters:

- `messages` (array)
- `threadId` (string)

### `list_labels` (~43 tokens)

List all Gmail labels (system + user). USE WHEN: you need label IDs/names before modify_labels, or to inspect the mailbox structure. SIDE EFFECTS: none.

Output parameters:

- `labels` (array)

### `list_snoozed` (~28 tokens)

List all snoozed threads with their due dates. SIDE EFFECTS: none.

Output parameters:

- `snoozed` (array)

### `modify_labels` (~98 tokens)

Add/remove labels on a thread. Archive = remove 'INBOX'; mark read = remove 'UNREAD'. USE WHEN: applying custom labels or label combinations in one call. DO NOT USE: for plain archive/read/unread — the dedicated tools are clearer. SIDE EFFECTS: changes the thread's labels; reversible by the inverse call.

Input parameters:

- `add` (array)
- `remove` (array)
- `threadId` (string, required)

Output parameters:

- `ok` (boolean)

### `bulk_modify` (~245 tokens)

Bulk-apply label changes to every message matching a Gmail query, batched at 1000 messages per API request. Returns matched/modified counts, affected thread IDs (capped at 500 — modifiedThreadCount has the true total), and per-chunk failures (partial success is reported, not hidden). If more messages match than maxMessages, only the first maxMessages are processed and 'capped' is true — raise maxMessages or re-run to finish the rest. Note: the query hits Gmail's search index as-is, WITHOUT the live re-verification search performs — for read-state-precise bulk ops, verify with search first. USE WHEN: mass operations — 'archive all newsletters older than 30 days' (query + remove INBOX), bulk labeling, bulk mark-read. DO NOT USE: for a single thread (use modify_labels or the dedicated tools), or with neither add nor remove. SIDE EFFECTS: modifies up to maxMessages messages in one call; label changes are reversible by the inverse call.

Input parameters:

- `add` (array)
- `maxMessages` (integer)
- `query` (string, required)
- `remove` (array)

Output parameters:

- `capped` (boolean)
- `failed` (array)
- `matchedMessages` (number)
- `modifiedMessages` (number)
- `modifiedThreadCount` (number)
- `modifiedThreads` (array)

### `archive` (~80 tokens)

Archive a thread (remove it from the inbox). USE WHEN: inbox triage — the thread is handled and should leave the inbox. DO NOT USE: to delete (use trash) or to defer to a date (use snooze). SIDE EFFECTS: thread leaves the inbox; reversible via modify_labels add INBOX.

Input parameters:

- `threadId` (string, required)

Output parameters:

- `ok` (boolean)

### `mark_read` (~36 tokens)

Mark a thread as read. SIDE EFFECTS: removes UNREAD; reversible via mark_unread.

Input parameters:

- `threadId` (string, required)

Output parameters:

- `ok` (boolean)

### `mark_unread` (~36 tokens)

Mark a thread as unread. SIDE EFFECTS: adds UNREAD; reversible via mark_read.

Input parameters:

- `threadId` (string, required)

Output parameters:

- `ok` (boolean)

### `trash` (~70 tokens)

Move a thread to Trash. USE WHEN: the thread should be discarded. DO NOT USE: for inbox cleanup of mail worth keeping (use archive). SIDE EFFECTS: thread moves to Trash; recoverable via untrash for ~30 days, then Gmail deletes it permanently.

Input parameters:

- `threadId` (string, required)

Output parameters:

- `ok` (boolean)

### `untrash` (~60 tokens)

Restore a thread from Trash. SIDE EFFECTS: removes the TRASH label; user labels are preserved, but INBOX is NOT re-added — use modify_labels (add INBOX) to return it to the inbox.

Input parameters:

- `threadId` (string, required)

Output parameters:

- `ok` (boolean)

### `download_attachment` (~127 tokens)

Download an attachment to a local file path. If MAILWARDEN_DOWNLOAD_DIR is set, destPath is resolved inside (and restricted to) that directory. USE WHEN: the user wants an attachment saved to disk (IDs come from get_thread's attachment metadata). SIDE EFFECTS: writes a local file; never overwrites — an existing file gets a numeric suffix (file-1.pdf). The response's 'saved' field is the path actually used. Mailbox unchanged.

Input parameters:

- `attachmentId` (string, required)
- `destPath` (string, required)
- `messageId` (string, required)

Output parameters:

- `saved` (string)

### `snooze` (~110 tokens)

Snooze a thread until a date (YYYY-MM-DD): archives it now, resurfaces on/after that date when sweep_snoozed runs. USE WHEN: deferring a thread to a later date instead of leaving it in the inbox. DO NOT USE: for permanent removal (use archive or trash). SIDE EFFECTS: removes INBOX, adds a dated MCP/Snoozed label; reversible via unsnooze.

Input parameters:

- `threadId` (string, required)
- `until` (string, required)

Output parameters:

- `snoozedUntil` (string)
- `threadId` (string)

### `unsnooze` (~44 tokens)

Cancel a snooze: return the thread to the inbox now. SIDE EFFECTS: removes the snooze label, restores INBOX.

Input parameters:

- `threadId` (string, required)

Output parameters:

- `threadId` (string)
- `unsnoozed` (boolean)

### `sweep_snoozed` (~95 tokens)

Resurface all snoozed threads whose date is due (<= today), batched at 1000 messages per API request. USE WHEN: the user asks to process due snoozes, or as a scheduled maintenance call. SIDE EFFECTS: due threads return to the inbox marked unread; safe to run repeatedly. failedCount/errors report messages a batch could not wake (their label is kept for the next sweep).

Output parameters:

- `date` (string)
- `errors` (array)
- `failedCount` (number)
- `woken` (array)
- `wokenCount` (number)

## Diagnostics

Captured diagnostic sections: Provenance, Vulnerabilities, Dependencies. The full working is on the page: https://verifymcp.io/servers/csitte-mailwarden/mailwarden#diagnostics

## Score history

- 2026-08-03: 29
- 2026-08-02: 78
- 2026-08-01: 18
- 2026-07-31: 6
- 2026-07-29: 24
- 2026-07-28: 24
- 2026-07-27: 24

## Links

- npm package: https://www.npmjs.com/package/mailwarden
- Socket report: https://socket.dev/npm/package/mailwarden
- Repository: https://github.com/csitte/mailwarden
- Changelog RSS feed: https://verifymcp.io/servers/csitte-mailwarden/mailwarden/changelog.xml
- Changelog JSON feed: https://verifymcp.io/servers/csitte-mailwarden/mailwarden/changelog.json
- HTML version of this page: https://verifymcp.io/servers/csitte-mailwarden/mailwarden