Plain Todo
An MCP server that lets AI coding agents turn a conversation into tasks in
a plain Markdown AGENT_TODO.md file kept in your repo.
About
Work agreed with an agent in one chat is easy to lose by the next session.
Plain Todo (plain-todo-mcp) gives the agents you run in Claude Code, Codex,
Cursor, or VS Code a shared to-do list for the repo: when you ask,
the agent pulls the concrete tasks out of the conversation and merges them
into AGENT_TODO.md, so you or another agent can pick up where it left off.
The list is ordinary Markdown that you can read, edit, and keep in git. The
server only reads and safely writes the file; the agent, which can see the
conversation, decides what goes in it.
Features
- Export agreed tasks from the current conversation into
AGENT_TODO.md, merged with the tasks already there and keeping what is done or open. - Keep a short Working Memory snapshot of what is in progress and what comes next at the top of the file.
- Mark open tasks done using commits made since the file was last saved as evidence.
- Schedule tasks to revisit with
Check after:dates, and park blocked work in a Waiting section that comes back when its date arrives. - Give a subfolder its own
AGENT_TODO.md, linked from the repo's root file. - Mark each saved file with front matter telling agents that open it directly to go through the server, while you stay free to edit it by hand.
- Write safely: an export based on an out-of-date read is rejected rather than overwriting someone else's changes, and malformed lists are refused.
Tools
| Tool | What it does | Changes files |
|---|---|---|
read_todo |
Reads AGENT_TODO.md with its revision, tasks that are due, and commits since it was last saved. |
No |
export_todo |
Saves the merged list, refusing it if the file changed since read_todo. |
Yes |
Quick Start
The server needs uv and Python 3.12 or later;
uvx downloads and starts it on demand:
uvx plain-todo-mcp
Started by hand, it waits for an MCP client on stdin; press Ctrl+C to stop.
Normally your client starts it. For Claude Code, add .mcp.json to the repo:
{
"mcpServers": {
"plain-todo": {
"command": "uvx",
"args": ["plain-todo-mcp"]
}
}
}
Then ask the agent to export the conversation to AGENT_TODO.md. The user
manual covers Codex, Cursor, VS Code, and the settings.
User Manual
See the User Manual for installation, client configuration, tools, settings, and troubleshooting.
Feedback
Report bugs and request features in GitHub Issues.
License
Metadata
Release files for plain-todo-mcp 0.5.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| plain_todo_mcp-0.5.0.tar.gz | 18.5 kB | With provenance | Details for plain_todo_mcp-0.5.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| plain_todo_mcp-0.5.0-py3-none-any.whl | Python 3 | none | any | Details for plain_todo_mcp-0.5.0-py3-none-any.whl |
Total release size: 31.6 kB
Release files / plain_todo_mcp-0.5.0.tar.gz
| Download URL | plain_todo_mcp-0.5.0.tar.gz |
|---|---|
| Size | 18.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
247147620bf2190b49f42482b4d6c7e90a0648395f946ac8868b39363d622c0e
|
|
BLAKE2b-256 checksum How to use checksums |
028ee0e6dc4689a73dd3b3319fd0619f619c82207842043e2218c44ab26e4d77
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logRelease files / plain_todo_mcp-0.5.0-py3-none-any.whl
| Download URL | plain_todo_mcp-0.5.0-py3-none-any.whl |
|---|---|
| Size | 13.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
7515f26939357da601f131b6d507791c6e669bfd9aa6853a92432b9767a6fe38
|
|
BLAKE2b-256 checksum How to use checksums |
bef86d40323118f548985d8a17e7eeefc0e37189f1df0cbde1187e3bda2c09e4
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logSecurity for plain-todo-mcp 0.5.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for plain_todo_mcp-0.5.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.