# mailwarden MCP server

> Lets an AI assistant perform full Gmail mailbox triage including searching, labeling, archiving, snoozing, and unsubscribing.

- Repository: https://github.com/csitte/mailwarden
- Page: https://hostedmcp.org/servers/csitte/mailwarden
- Transport: stdio
- Stars: 0
- License: MIT
- Latest version: 0.31.2

## Install

### Claude Code

```sh
claude mcp add mailwarden -- npx -y mailwarden
```

### Cursor (`~/.cursor/mcp.json`)

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

### VS Code (`.vscode/mcp.json`)

```json
{
  "servers": {
    "mailwarden": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "mailwarden"
      ]
    }
  }
}
```

### VS Code CLI

```sh
code --add-mcp '{"name":"mailwarden","type":"stdio","command":"npx","args":["-y","mailwarden"]}'
```

### Claude Desktop (`claude_desktop_config.json`)

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

### Codex

```sh
codex mcp add mailwarden -- npx -y mailwarden
```

### Codex config.toml (`~/.codex/config.toml`)

```toml
[mcp_servers.mailwarden]
command = "npx"
args = ["-y", "mailwarden"]
```

### Gemini CLI

```sh
gemini mcp add -s user mailwarden npx -- -y mailwarden
```

### Gemini settings.json (`~/.gemini/settings.json`)

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

## Environment variables

| Name | Required | Secret | Description |
|---|---|---|---|
| `MAILWARDEN_ACCOUNT` | no | no |  |
| `MAILWARDEN_AUTO_SWEEP` | no | no | Set to 1 to sweep due snoozes at startup and hourly while running |
| `MAILWARDEN_CREDENTIALS` | no | no | Path to the Google OAuth credentials.json (Desktop app client) |
| `MAILWARDEN_DIR` | no | no | Config directory (default ~/.mailwarden), holds credentials.json and token.json |
| `MAILWARDEN_DOWNLOAD_DIR` | no | no | Restrict download_attachment and export_thread writes to this directory (recommended for HTTP hosting) |
| `MAILWARDEN_TOKEN` | no | no |  |
| `MAILWARDEN_TOOLS` | no | no |  |

## Tools (21)

- `search`
- `get_thread`
- `read_attachment`
- `list_labels`
- `get_profile`
- `what_changed`
- `follow_ups`
- `list_unsubscribe`
- `create_label`
- `modify_labels`
- `undo_bulk_modify`
- `download_attachment`
- `export_thread`
- `list_filters`
- `preview_filter`
- `create_filter`
- `delete_filter`
- `create_draft`
- `update_draft`
- `bulk_modify`
- `mailto`

## FAQ

### Does this server support snoozing emails?

Yes, it features mailbox-side snooze which archives a thread and makes it resurface in the inbox on a specified date.

### Is the search feature accurate regarding unread messages?

Yes, the search tool re-verifies every hit against live labels to prevent the stale read-state drift common in Gmail's index.

### How does it handle sender authentication?

It reports SPF/DKIM/DMARC results recorded by Gmail's own receiving server to verify if a sender is legitimate.
