Airpost
Agents

Claude Code as a mail assistant

Give Claude Code your mail, either through airpost-mcp with an access level or through the airpost CLI with the agent skill.

What you’ll build

A Claude Code setup where you can ask things like “what did the auditors send last week, and save the attachments into ./audit” or “draft a reply to Dana’s contract thread” from your terminal. You pick one of two ways in:

airpost-mcpairpost CLI + skill
What the agent callsMCP tools (search_mail, reply_to_thread, …)airpost commands in the shell
LimitsAccess level, hidden accounts and folders, audit logNone: your full rights
Good forDay-to-day assistanceScripting tasks you’d otherwise do yourself

Use the MCP route unless you want the agent to have everything you have. Don’t give one agent both.

Prerequisites

  • Airpost with airpost and airpost-mcp. See Install the CLI.
  • An engine running (the desktop app, or airpost engine install).
  • Claude Code with claude on your PATH.

Route A: airpost-mcp

Register the server

airpost-mcp install --client claude-code

This runs claude mcp add-json airpost ... --scope user. To register it only for one project instead, write the entry into that project’s .mcp.json:

cd ~/work/acme
airpost-mcp install --client claude-code --config-file .mcp.json

Pick the access level

Leave it at Read mail for questions and search. Choose Read and draft in Preferences > MCP if you want the agent to write drafts and archive. Sending stays with you unless you choose Read, draft and send.

Check it

airpost-mcp status
claude mcp list

claude mcp list shows airpost as connected.

Ask

claude
> Find the mail from the auditors in the last two weeks and save every
  PDF they attached into ./audit.

Claude calls search_mail (with something like from:auditor has:attachment after:2w), get_thread to see the files arrays, and get_attachment, whose result includes the file’s local path. It then copies those files with its own shell tools.

Route B: the CLI and the agent skill

The CLI acts with your full rights. Access levels, hidden folders and the audit log don’t apply to it.

Install the skill

airpost skill install --agent claude

This writes ~/.claude/skills/airpost. Use --project to put it in ./.claude/skills for one repository.

Ask

> Archive everything from notifications@github.com older than a week,
  but show me the dry run first.

The skill teaches Claude to run the dry run before the change:

airpost archive --query 'from:notifications@github.com before:7d' --dry-run --json
airpost archive --query 'from:notifications@github.com before:7d' --wait --json

and to report the undo token from the result.

Expected output

For the attachment question with Route A, Claude ends with something like:

Saved 3 files to ./audit:
  ./audit/Q3-findings.pdf      (from "Q3 audit: findings", Oct 30)
  ./audit/management-letter.pdf
  ./audit/PBC-list-v2.pdf

The calls are in the audit log:

airpost-mcp status          # prints the audit log path
tail -n 5 "<config-dir>/mcp-audit.log" | jq -c '{toolName, outcome}'

How it works

airpost-mcp install writes a stdio entry that runs the airpost-mcp binary by full path with --config-dir pinned, so Claude Code always reaches the same profile. airpost-mcp talks to the running engine over its local socket; nothing goes through a server. The policy file is read on every call, so changing the level takes effect on the next tool call.

The skill is a SKILL.md built into the airpost binary. It tells Claude when to use the CLI, the search grammar, the draft flow (draft reply, draft validate, draft send) and the safety rules.

Variations

  • Project-scoped mail. Combine --config-file .mcp.json with hidden accounts so a work repository only sees the work account.
  • Codex. airpost-mcp install --client codex or airpost skill install --agent codex.
  • Remote engine. If your engine runs on a server, use MCP over HTTP with a bearer token instead of stdio. See Always-on VPS.

Cleanup

airpost-mcp uninstall --client claude-code
airpost skill uninstall --agent claude