Todokit

Provides an MCP server for Todokit tasks with JSON persistence and rich todo operations.

typescript

0

GitHub Stars

typescript

Language

6 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "j0hanz-todokit-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@j0hanz/todokit-mcp@latest"
      ],
      "env": {
        "TODOKIT_TODO_FILE": "/path/to/todos.json"
      }
    }
  }
}

You have an MCP server for Todokit that exposes a suite of task management capabilities via MCP tools. It stores todos in JSON locally and supports safe bulk operations, filtering, and rich item management, all accessible from your MCP client without exposing an HTTP endpoint.

How to use

You use this server by starting it through your MCP client or runtime that supports stdio MCP connections. The server runs in stdio mode and registers a set of tools on startup. From your MCP client, you can add, list, update, complete, and delete todos using the provided tool endpoints. All interactions return JSON payloads with either ok: true and a result, or an error object when something goes wrong. Use the filtering and pagination options to tailor lists to your needs, and rely on dry-run options when deleting multiple items to prevent accidental data loss.

Key capabilities include adding single or multiple todos, listing with filters (status, priority, tag, due dates, search text), updating fields (title, description, dueDate, tags, completion status), marking items complete, and deleting single or multiple todos with safety previews.

How to install

npx -y @todokit/mcp@latest

From source run flow

If you prefer to run from source, install dependencies, build, and start the server in the following sequence.

git clone https://github.com/j0hanz/todokit-mcp-server.git
cd todokit-mcp-server
npm install
npm run build
npm start

Available tools

add_todo

Add a new todo item with title, optional description, priority, dueDate, and tags. Returns the created item and a summary.

add_todos

Add multiple todos in a single call. Each item can include title, description, priority, dueDate, and tags; returns the created items and a summary.

list_todos

List todos with optional filters for status, priority, tags, due dates, and a free-text query. Includes pagination and summary counts.

update_todo

Update fields on a todo identified by id or a query. Supports changing title, description, completion, priority, dueDate, and tags.

complete_todo

Set a todo's completion status by id or a query. Returns the updated item and a contextual summary.

delete_todo

Delete a single todo by id or query, with an optional dryRun for previewing deletions.

delete_todos

Delete multiple todos matching filters with safety defaults and an optional dryRun preview.