todo-mcp-server-kit
An MCP server for a plaintext todo list.
It exposes a project-local .claude/todos.md through MCP Tools (create /
edit / complete / delete / search), Resources (list views + aggregate
stats, including URI-templated views), and Prompts (weekly review /
daily plan) — plus a built-in browser dashboard for visual editing.
The on-disk format is plain, human-readable Markdown, so your todos stay readable and version-controllable without this tool.
Install & run
Zero-install with uv (recommended):
uvx todo-mcp-server-kit --project-root /path/to/your/project
Or install from PyPI:
pip install todo-mcp-server-kit
todo-mcp-server-kit --project-root /path/to/your/project
The server speaks MCP over stdio — it is normally launched by an MCP client (Claude Code, Cursor, …), not run by hand.
--project-root is optional; resolution order is:
--project-root > $TODO_MCP_PROJECT_ROOT > current working directory.
Todos live in <project-root>/.claude/todos.md.
Register with Claude Code
claude mcp add todo -s user -- uvx todo-mcp-server-kit --project-root /path/to/your/project
Or, in any MCP client config (mcpServers):
{
"mcpServers": {
"todo": {
"command": "uvx",
"args": ["todo-mcp-server-kit", "--project-root", "/path/to/your/project"]
}
}
}
Capabilities
Tools (tools/call)
| Tool | Signature | Purpose |
|---|---|---|
add_todo |
(text, priority="med", due=None, tags=None) |
Create a todo |
mark_done |
(id) |
Mark complete |
edit_todo |
(id, text?, priority?, due?, done?, tags?) |
Edit fields (done=False to reopen; tags=[] to clear) |
remove_todo |
(id) |
Delete |
search_todos |
(query?, tag?, priority?, status="all", due_before?, due_after?) |
Filter by any combination of criteria |
open_dashboard |
() |
Get the dashboard URL |
Resources (resources/read)
| URI | Type | Content |
|---|---|---|
todo://list |
markdown | Full todos.md |
todo://tag/{tag} |
markdown | Todos carrying a tag (URI template) |
todo://status/{status} |
markdown | open / done view (URI template) |
todo://stats |
json | Counts, completion rate, by-priority/by-tag, overdue, due-soon |
Prompts (prompts/get)
| Prompt | Purpose |
|---|---|
weekly_review |
Review the week: done / open / overdue + next-week focus |
daily_plan |
Plan today: surface overdue, pick a Top-3 from open items |
Browser dashboard
On startup the server runs a small HTTP dashboard in a daemon thread
(default http://localhost:8765, falling back to the next free port). It
renders todos as an interactive table — view, add, edit, complete, tag, and
delete — and re-reads the file on every request. Call open_dashboard to get
the URL.
Bound to
127.0.0.1only, no auth — intended for local personal use; don't expose the port. The dashboard lives and dies with the server process.
Data format
Each todo is one Markdown line under <project-root>/.claude/todos.md:
- [ ] #12 [high] (due: 2026-06-01) (tags: agent,learning) Finish the v2 spec
due and tags are optional. See docs/FORMAT.md for the
full grammar.
Docs
docs/FORMAT.md— thetodos.mdline grammar (single source of truth)CONTRIBUTING.md— dev setup & tests
License
MIT © Zhang Yu
Metadata
Release files for todo-mcp-server-kit 0.2.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 |
|---|---|---|---|---|
| todo_mcp_server_kit-0.2.0.tar.gz | 18.9 kB | With provenance | Details for todo_mcp_server_kit-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| todo_mcp_server_kit-0.2.0-py3-none-any.whl | Python 3 | none | any | Details for todo_mcp_server_kit-0.2.0-py3-none-any.whl |
Total release size: 35.1 kB
Release files / todo_mcp_server_kit-0.2.0.tar.gz
| Download URL | todo_mcp_server_kit-0.2.0.tar.gz |
|---|---|
| Size | 18.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
952aa4bd130758c7f91522a9be5fab45a7598a4fc978d43c9a77408ae90553ed
|
|
BLAKE2b-256 checksum How to use checksums |
a8e822b969ef20afe2837dc0ef6bd30f5c1b6f4449b5a6c16575d6bd56f07297
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 May 29, 2026.
Transparency logRelease files / todo_mcp_server_kit-0.2.0-py3-none-any.whl
| Download URL | todo_mcp_server_kit-0.2.0-py3-none-any.whl |
|---|---|
| Size | 16.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
3de4e5bbc8e7f61952ad56e626b80adbb8e991fec4000c62d37dc258df1c1d24
|
|
BLAKE2b-256 checksum How to use checksums |
2f8495ff335d2479d71f5d2d943fd1223f68fb26d92166b34bf25ffbad671b4c
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 May 29, 2026.
Transparency logSecurity for todo-mcp-server-kit 0.2.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 todo_mcp_server_kit-0.2.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 May 29, 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.