Skip to main content

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.

Latest version on PyPI Supported Python versions License: MIT


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

MIT

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)

Source distribution for plain-todo-mcp 0.5.0
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)

Table of built distributions (wheels) for plain-todo-mcp 0.5.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.5.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page