GhostPaw Email

@ghostpaw/email

Agent email: IMAP and SMTP in-process, cached in SQLite, with reading and sending as separate tools.

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh

A standalone email engine for Node.js, built on SQLite.

Email treats IMAP sync, SMTP send, local caching, threading, search, and transport errors as one coherent model instead of a grab bag of protocol adapters. It ships as a single prebundled blob with zero runtime dependencies, designed for three audiences at once: human developers working directly in code, LLM agents operating through a structured soul / tools / skills runtime, and agent operators who want a ready-to-use email CLI binary without writing any wiring code.

MCP server

Every client below starts the same stdio server: ghostpaw-email mcp. For npm-based environments, use npx -y @ghostpaw/email mcp instead. Cached messages live in ~/.ghostpaw/email.db unless the GHOSTPAW_EMAIL_DB environment variable (absolute path) or --db says otherwise.

Claude Code

claude mcp add ghostpaw-email -- ghostpaw-email mcp

or as a plugin, which also installs the skill:

/plugin marketplace add GhostPawJS/email

/plugin install ghostpaw-email@ghostpaw-email

Email CLI (~/.email/config.toml)

[mcp_servers.ghostpaw-email]

command = "ghostpaw-email" args = ["mcp"]

Cursor (.cursor/mcp.json), Claude Desktop (claude_desktop_config.json) or a project .mcp.json:

{

"mcpServers": { "ghostpaw-email": { "command": "ghostpaw-email", "args": ["mcp"] } } }

Claude Desktop users can also install server.mcpb from the latest GitHub release. A Dockerfile is included for container hosts: docker build -t ghostpaw-email . && docker run -i --rm -v email:/data ghostpaw-email.

The server speaks MCP 2026-07-28 (stateless, server/discover) and the initialize-based revisions 2025-11-25, 2025-06-18, 2025-03-26 and 2024-11-05.

Network operations use the existing CLI account configuration (email account add) or EMAIL_IMAP_HOST, EMAIL_SMTP_HOST, EMAIL_USER and EMAIL_PASS (or EMAIL_ACCESS_TOKEN). Discovery and cached reads need no account or credentials. The surface database defaults to ~/.ghostpaw/email.db; point --db at an existing account cache to read it. Each network call opens and closes its IMAP session. Connection commands do not retain a session between calls.

On POSIX, new accounts files and SQLite caches (including WAL/SHM sidecars) use mode 0600, and newly created storage directories use 0700. Existing permissions are preserved, except rewriting accounts.json sets it to 0600.

Use ghostpaw-email skill --short for a compact command cheat sheet, ghostpaw-email skill for the full reference, and ghostpaw-email skill --list to list guides.

Noun-verb CLI

Both email and ghostpaw-email accept this additive command tree. Existing account, read, search, compose, organize and sync commands retain their flags, output and exit codes. Use mail --help for the new tree and mail --help for parameters.

mail read | search

mail send | reply | forward | draft | update-draft | send-draft mail mark-read | mark-unread | star | unstar | mark-answered mail copy | move | archive | trash | junk | not-junk mail set-labels | add-labels | remove-labels mail create-folder | rename-folder | delete-folder | subscribe-folder | unsubscribe-folder mail connect | disconnect | reconnect | sync | refresh-folders | watch

These 33 paths map to the 5 aligned tools. Action verbs set the tool's action; draft sets save_draft. Search accepts its query as a positional argument. Other fields use kebab-case flags, such as --folder INBOX --uids 1 --uids 2 and --input @message.json for a compose payload. Arrays accept repeated flags or JSON; objects accept JSON. Values are literal, including a leading @. Two flags read files: --input on the mail compose verbs and --body on compose send|reply|draft. On those, @path reads the file, @- reads stdin and @@text passes @text; help marks them (@file, @- stdin, @@ literal @). An empty or unreadable path exits 2. A single - reads stdin JSON; explicit flags override stdin fields. -- ends option parsing.

Global flags for the new commands: --db , --json, --quiet, --compact, --help/-h, --version/-V/-v, --no-color. Output is JSON when piped or when --json is set. --quiet suppresses stdout. completions bash|zsh|fish prints shell completion setup; version prints the version and installation variant. The existing tools [--json], describe , call [JSON|-], flat mail_ --parameter value, mcp and skill forms remain available.

Offline examples, run against an empty cache:

ghostpaw-email mail search invoice --db /tmp/email-port-example.db --json

ghostpaw-email mail read --view folders --db /tmp/email-port-example.db --json ghostpaw-email mail --help

Search returns 0 matches and folder reads return 0 folders in an empty cache. GHOSTPAW_EMAIL_DB sets the default cache path, otherwise ~/.ghostpaw/email.db is used. Local search and cached reads need no credentials. Network operations use email account add configuration or EMAIL_IMAP_HOST, EMAIL_SMTP_HOST, EMAIL_USER and EMAIL_PASS (or EMAIL_ACCESS_TOKEN). Each invocation closes its network session; mail connect does not retain a session for later commands.

Tool CLI

ghostpaw-email tools

ghostpaw-email call mail_read '{"view":"folders"}' --db :memory: ghostpaw-email call mail_search '{"query":"invoice"}'

Both email and ghostpaw-email run the same CLI. Existing account, read, search, compose, organize and sync commands remain available. The full guide is preserved in skills/email/references/cli.md.

Agent Skill: SKILL.md and skills/email/ ship in the package; print the skill with ghostpaw-email skill. List guides with ghostpaw-email skill --list and print one with ghostpaw-email skill compose-and-send.

Install

Release binary (default)

Each line downloads the latest release asset, checks it against the release's SHA256SUMS and installs it on the PATH (~/.local/bin on Linux/macOS; the Windows script adds its folder to the user PATH).

These lines never edit ~/.profile or other shell startup files: export PATH applies to the current shell only. To keep it in new shells, use the ~/.profile line below.

linux-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target linux-x64 && export PATH="$HOME/.local/bin:$PATH"

linux-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target linux-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-arm64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target darwin-arm64 && export PATH="$HOME/.local/bin:$PATH"

darwin-x64:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target darwin-x64 && export PATH="$HOME/.local/bin:$PATH"

windows-x64 (PowerShell; persistently adds its folder to the user PATH by default):

irm https://raw.githubusercontent.com/GhostPawJS/email/main/install.ps1 | iex

Pinned to a release:

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target linux-x64 --version 0.5.10 && export PATH="$HOME/.local/bin:$PATH"

Also adding ~/.local/bin to ~/.profile (edits ~/.profile once; skipped if it already mentions ~/.local/bin; zsh login shells read ~/.zprofile instead, so use that file name there):

curl -fsSL https://raw.githubusercontent.com/GhostPawJS/email/main/install.sh | sh -s -- --target linux-x64 && { grep -qs '.local/bin' ~/.profile || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.profile; } && export PATH="$HOME/.local/bin:$PATH"

To skip the persistent user PATH edit (the installer still installs and prints the folder to add):

$env:GHOSTPAW_NO_MODIFY_PATH=1; irm https://raw.githubusercontent.com/GhostPawJS/email/main/install.ps1 | iex

$ ghostpaw-email --version

email 0.5.10 (binary, linux-x64)

Scripts that compare versions should use --version --short or --version --json.

A session with the 0.5.1 linux-x64 binary against a local GreenMail test server on 127.0.0.1 (throwaway user, no real account) and a fresh database (output piped through jq to keep it short):

The same session as an animated GIF.

Other release installers:

mise use -g github:GhostPawJS/email

ubi --project GhostPawJS/email --exe ghostpaw-email --in ~/.local/bin eget GhostPawJS/email

For aqua, define a github_release package in aqua.yaml:

registries:

• name: email type: local path: email-registry.yaml

packages:

• name: GhostPawJS/email@v registry: email

email-registry.yaml:

packages:

• type: github_release repo_owner: GhostPawJS repo_name: email asset: ghostpaw-email-{{trimV .Version}}-{{.OS}}-{{.Arch}}.tar.gz format: tar.gz replacements: { amd64: x64 } overrides:
• goos: windows asset: ghostpaw-email-{{trimV .Version}}-windows-{{.Arch}}.zip format: zip files:
• name: ghostpaw-email

Install scripts verify SHA256SUMS. To verify a downloaded archive's build attestation:

gh attestation verify <archive> -R GhostPawJS/email

Set GHOSTPAW_VERIFY=attestation for attestation verification in install.sh. Binaries are unsigned; macOS binaries carry an ad-hoc signature. For a browser download on macOS, remove quarantine with xattr -d com.apple.quarantine /path/to/ghostpaw-email. Linux binaries requ