Skip to main content

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.1 only, 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

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)

Source distribution for todo-mcp-server-kit 0.2.0
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)

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

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

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

Select from 2 files

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