How do I install Agentmailkit?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Agentmailkit need an API key?

No required environment variable is listed on this record.

What transport does Agentmailkit use?

Agentmailkit runs locally over stdio.

When was Agentmailkit last checked?

Last checked 2026-11-09. Run scheduled LLM-written email digests from local files and feeds. Local-first MCP server.

Agentmailkit MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

uvx agentmailkit==0.2.2

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1claude mcp add io.github.ariaxhan-agentmailkit -- uvx agentmailkit==0.2.2

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.ariaxhan-agentmailkit": {4      "command": "uvx",5      "args": [6        "agentmailkit==0.2.2"7      ]8    }9  }10}

claude_desktop_config.json

Local · pypiPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version: 0.2.2
Last checked

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

agentmailkit

For agents

You are an AI coding agent reading this to decide whether to install agentmailkit and how to call it. Run this:

pip install 'agentmailkit[mcp]'
claude mcp add agentmailkit -- agentmailkit mcp

Gemini CLI: gemini extensions install https://github.com/ariaxhan/agentmailkit.

Then call list_jobs with no arguments: it returns the five example jobs that ship inside the wheel, so it works before any config exists. preview_job(job_id=..., model="echo") renders one to a local file with no API key. run_job(job_id=...) defaults to dry_run=true; only dry_run=false sends real email.

Full tool reference, argument names and the Codex config snippet: llms.txt.

Scheduled, LLM-written email digests that run on your machine, read your own files, and send from your own inbox.

→ See real emails it produces

Live samples, generated end to end. Nothing hand-written. Start there, it explains this faster than the README can.

pip install agentmailkit
agentmailkit run morning-brief --dry-run   # five example jobs ship with it, so this works immediately
agentmailkit quickstart                    # render all five to a local HTML gallery; never sends
agentmailkit init                          # copy them into ./jobs to make them yours

MIT licensed. No account, no vendor, no cloud required.

What it is

An email is two files: a JSON job and a markdown prompt.

{
  "id": "morning-brief",
  "schedule": "0 7 * * *",
  "sources": ["papers=arxiv:cs.AI#6", "weather=weather:Brooklyn"],
  "render": "warm",
  "delivery": "gmail",
  "dedup": true
}

The engine runs one fixed pipeline and never grows a special case:

gather sources -> render prompt -> generate -> gate -> theme -> deliver -> post

Why not the built-in schedulers

ChatGPT Tasks, Claude Routines, Gemini Scheduled Actions and Copilot all execute in the vendor's cloud, which costs them two things:

They cannot read the files on your computer. Not ~/notes, not a local database, not your git working tree.
They cannot send real email from your inbox. Output stays inside their app.

agentmailkit runs where your data already is. Nothing is uploaded except the prompt you choose to send to a model, and with a local model, not even that.

And it is deterministic. It is not an autonomous agent: it does not decide things, wander your filesystem, or act unrequested. The model writes the words; the engine owns everything else, so the same job produces the same shaped email every run. Local OSS agents can also read files and send mail, but they are broad autonomous systems you configure down to a task. This does one job, predictably, for years.

Full comparison including the honest counter-case: docs/comparison.md.

Hand it to your coding agent

Hand your coding agent this link and it will set the whole thing up, asking you the right questions as it goes:

https://github.com/ariaxhan/agentmailkit/blob/main/AGENTS.md

AGENTS.md is a complete setup runbook: what to ask you, how to install, how to build your first job, how to verify before anything can send, and how to schedule it. CLAUDE.md is a symlink to the same file, so they can never drift apart.

Use from Claude Code

agentmailkit speaks MCP, so your coding agent can drive it as a tool instead of you typing commands.

pip install 'agentmailkit[mcp]'
claude mcp add agentmailkit -- agentmailkit mcp

Codex, in ~/.codex/config.toml:

[mcp_servers.agentmailkit]
command = "agentmailkit"
args = ["mcp"]

Tool	What it does
`list_jobs`	Every configured job with its schedule, sources and delivery target
`preview_job`	Renders what one job would email, to a local file. Cannot send
`run_job`	Runs one job. `dry_run` defaults to true
`list_plugins`	Every registered source, model, gate, delivery backend and theme

Or in Docker, with your jobs on a mounted volume: docker run -i --rm -v /path/to/jobs:/data mcp/agentmailkit.

Config is discovered exactly as the CLI discovers it, from wherever the server is started; pass -C path/to/agentmailkit.json in the args to pin one.

run_job with dry_run=false sends real email from your configured inbox. Every other tool, and the default dry_run=true, stops before delivery.

Needs Python 3.10 or newer, which is the MCP SDK's floor, not agentmailkit's.

What ships

Job	Pulls	Interesting because
`morning-brief`	weather, three news outlets, on-this-day	Outlets stay labelled, so the model can contrast their framing
`curiosity`	archaeology and astronomy feeds, history	No work content at all, on purpose
`research-digest`	Hugging Face, arXiv	Real ids, counts and links the model cannot invent
`repo-pulse`	git log, diffstat, TODO markers	Reads your working tree, which no cloud scheduler can
`daily-brief`	local files, git log	The minimal shape to copy

Ten sources built in: file, glob, recent, shell, hf, arxiv, rss, news, history, weather. Anything with a feed or an API joins them in about thirty lines.

Ideas worth stealing: your city's council agendas, security advisories for your exact dependency list, exchange rates, a friend's blog, release notes for the tools you use, tide tables, ISS pass times over your house.

Nothing repeats. A seen-ledger strips already-sent items before the model ever sees them, so day two is not a reprint of day one.

Docs


Quickstart	Five minutes to a real email
Setup guide for agents	Hand this to your coding agent
Sources	All ten, with arguments and examples
Jobs and prompts	Every job field, prompt conventions
Themes	The renderer, palettes, enforced house style
Dedup	The seen-ledger contract
Delivery and config	Gmail, SMTP, gates, configuration
Models	Backends, and why they are text-only
Scheduling	cron, launchd, systemd, CI, and the cloud tradeoff
Taper pieces	The optional computational-poetry companion
Plugins	Write a source in about thirty lines
Comparison	Versus cloud schedulers and local agents, honestly

Install

pip install agentmailkit            # core, standard library only
pip install agentmailkit[gmail]     # + Gmail delivery
pip install agentmailkit[all]       # + Anthropic and OpenAI backends
pip install agentmailkit[mcp]       # + the MCP server, to drive it from a coding agent

The core has zero required dependencies. Backends pull their own libraries only when enabled.

Published on PyPI: pypi.org/project/agentmailkit. Requires Python 3.9 or newer.

Status

Alpha (0.2.2, on PyPI). Engine, plugins, dedup, themes, delivery and scheduler emitters all work and are exercised end to end against live APIs. quickstart renders a full sample set from your own data on first run, with no keys and no network round-trip, and cannot send by construction.

Known rough edges: the five shipped jobs carry example defaults (weather:Brooklyn, a fixed news trio) that you are expected to edit after agentmailkit init.

Contributing

Issues and pull requests welcome. The rule that governs review: behaviour is configuration, not code. If a change adds an if to the engine for one email's sake, it probably wants to be a plugin.

License

MIT. See LICENSE.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Agentmailkit?

Does Agentmailkit need an API key?

What transport does Agentmailkit use?

When was Agentmailkit last checked?

Documentation

agentmailkit

For agents

→ See real emails it produces

What it is

Why not the built-in schedulers

Hand it to your coding agent

Use from Claude Code

What ships

Docs

Install

Status

Contributing

License