Run scheduled, LLM-written email digests from local files and feeds directly from your own inbox.
Also known as ariaxhan/agentmailkit
- Stars
- 1
- Tools
- —
- Downloads, 30 days
- 199
- Latest version
- 0.2.2
- Last commit
- Aug 28, 2026
- License
- MIT
What is agentmailkit MCP?
agentmailkit runs scheduled, LLM-written email digests from local files and feeds directly from your own inbox.
Summary generated from the project's README
About agentmailkit MCP server
Automating scheduled, LLM-written email digests from local files and personal feeds is what agentmailkit enables. Unlike cloud-based schedulers, this tool runs on your own machine, allowing it to access local data like git working trees, notes, or databases that vendor tools cannot reach. It uses a deterministic pipeline to gather sources, render prompts, and deliver formatted emails directly from your own inbox via Gmail or SMTP.
Developers can manage these tasks through an MCP interface, using tools like list_jobs to view schedules or preview_job to render an email to a local file without sending it. The system includes built-in sources for arXiv, Hugging Face, RSS, and weather, alongside a seen-ledger to ensure no content repeats in subsequent digests. Because it runs locally, you maintain control over your data, and the engine ensures that the same job produces a consistent shape every time it runs.
What you can do with it
- 1Preview email content safelyRequest a rendering of a scheduled job to a local file to verify the layout before any actual delivery occurs.
Written from the project's README. Every use case is checked against a quote from it.
How to install agentmailkit MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall agentmailkit MCP in Claude Code
$ claude mcp add agentmailkit -- uvx agentmailkitInstall agentmailkit MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"agentmailkit": {
"command": "uvx",
"args": [
"agentmailkit"
]
}
}
}Install agentmailkit MCP in VS Code
.vscode/mcp.json
{
"servers": {
"agentmailkit": {
"type": "stdio",
"command": "uvx",
"args": [
"agentmailkit"
]
}
}
}Install agentmailkit MCP in VS Code CLI
$ code --add-mcp '{"name":"agentmailkit","type":"stdio","command":"uvx","args":["agentmailkit"]}'Install agentmailkit MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"agentmailkit": {
"command": "uvx",
"args": [
"agentmailkit"
]
}
}
}Install agentmailkit MCP in Codex
$ codex mcp add agentmailkit -- uvx agentmailkitInstall agentmailkit MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.agentmailkit] command = "uvx" args = ["agentmailkit"]
Install agentmailkit MCP in Gemini CLI
$ gemini mcp add -s user agentmailkit uvx -- agentmailkitInstall agentmailkit MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"agentmailkit": {
"command": "uvx",
"args": [
"agentmailkit"
]
}
}
}Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableariaxhan/agentmailkit is public and reachablegithub.com/ariaxhan/agentmailkit ↗Pass
- Package names this repository as its sourceagentmailkit names ariaxhan/agentmailkit as sourcepypi.org/project/agentmailkit/ ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-08-28github.com/ariaxhan/agentmailkit ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from agentmailkitPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubagentmailkit
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.
agentmailkit MCP questions
How do I add agentmailkit MCP to Claude Code?
Run claude mcp add agentmailkit -- uvx agentmailkit in your terminal. Add --scope user to make it available in every project.
How do I add agentmailkit MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
Can it read my local files?
Yes, unlike cloud-based schedulers, agentmailkit runs on your machine and can read your local notes, databases, and git working trees.
How do I test it without configuring anything?
You can call list_jobs to see five example jobs that are included by default, and use preview_job to render them to a local file without an API key.