todokit-mcp

An MCP server for Todokit, a task management and productivity tool with JSON storage.

One-Click Install

Features

• Task management: add, update, complete/reopen, and delete todos.
• Batch operations: add multiple todos and bulk delete with filters.
• Rich filtering: status, priority, tags, due dates, and free-text search.
• Tagging: tags are normalized (trimmed, lowercase, unique) and can be added or removed.
• Safe deletion: dry-run previews before deleting; bulk delete defaults to a safety limit.
• JSON persistence with queued writes and atomic file writes.
• Optional diagnostics events (tool calls/results, storage, lifecycle) via Node diagnostics channels.
• List summaries with counts (pending, completed, overdue) and pagination metadata.

Quick Start

npx -y @j0hanz/todokit-mcp@latest

The server runs over stdio (no HTTP endpoint) and registers MCP tools on startup.

Installation

NPX (recommended)

npx -y @j0hanz/todokit-mcp@latest

Global install

npm install -g @j0hanz/todokit-mcp

Then run:

todokit-mcp

From source

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

Configuration

Storage path

By default, todos are stored in todos.json next to the server package (the project root when running from source). To control where data is written, set the TODOKIT_TODO_FILE environment variable to an absolute or relative path ending with .json. Relative paths resolve from the current working directory. The directory is created as needed; if the file does not exist, the server starts with an empty list.

Examples:

# macOS/Linux
TODOKIT_TODO_FILE=/path/to/todos.json npx -y @j0hanz/todokit-mcp@latest

# Windows PowerShell
$env:TODOKIT_TODO_FILE = 'C:\path\to\todos.json'
npx -y @j0hanz/todokit-mcp@latest

JSON formatting

By default, todos are written as pretty-printed JSON (2-space indentation). To write compact JSON instead, set TODOKIT_JSON_PRETTY to 0 or false.

TODOKIT_JSON_PRETTY=0 npx -y @j0hanz/todokit-mcp@latest

CLI options

The server accepts a few CLI flags (use -- to forward args when running via npx).

npx -y @j0hanz/todokit-mcp@latest -- --todo-file ./todos.json --diagnostics --log-level debug

The log level is only used when diagnostics output is enabled.

Diagnostics

Diagnostics events are always published on Node's diagnostics_channel and can be subscribed to programmatically. When --diagnostics is set, the server attaches default subscribers and prints JSON events to stderr (stdout stays reserved for MCP traffic).

Channels:

• todokit:tool — tool call + tool result events
• todokit:storage — read/write/close events
• todokit:lifecycle — shutdown events

Tools

All tools return a JSON payload in both content (stringified) and structuredContent. Inputs are validated with strict Zod schemas, so unknown fields are rejected.

Success payload:

{
  "ok": true,
  "result": {}
}

Error payload:

{
  "ok": false,
  "error": { "code": "E_CODE", "message": "Details" }
}

The result shape is tool-specific. If a query matches multiple todos, most tools return E_AMBIGUOUS with preview matches and a hint to use an exact id. delete_todo with dryRun: true instead returns an ok response with matches and totalMatches for preview.

add_todo

Add a new todo item.

Result fields:

• item (todo)
• summary
• nextActions

add_todos

Add multiple todo items in one call.

Result fields:

• items (todos)
• summary
• nextActions

list_todos

List todos with filtering, search, sorting, and pagination.

Result fields:

• items (todos)
• summary
• counts (total, pending, completed, overdue)
• limit
• offset
• hasMore (true if more results are available after this page)

Notes:

• Overdue calculations compare dueDate against the server's local calendar date (YYYY-MM-DD).

update_todo

Update fields on a todo item. Provide either id or query to identify the todo.

Notes:

• If both tags and tagOps are provided, tags wins and replaces the list.
• If no updatable fields are provided, the tool returns an error.

Result fields:

• item (todo)
• summary
• nextActions

complete_todo

Set completion status for a todo item. Provide either id or query.

Result fields:

• item (todo)
• summary (includes already-complete or reopen messages)
• nextActions

delete_todo

Delete a todo item. Provide either id or query.

Result fields:

• deletedIds (array)
• summary
• nextActions (only when not dryRun)
• dryRun (when dryRun is true)
• matches, totalMatches (dry-run + multiple matches)

delete_todos

Delete multiple todos matching filters. At least one filter is required; defaults to limit=10 for safety.

Notes:

• At least one filter (status, priority, tag, dueBefore, dueAfter, query) is required.
• The default limit of 10 prevents accidental mass deletions.

Result fields:

• deletedIds (array)
• summary
• totalMatched
• matches (dry-run only, array of previews)
• dryRun (when dryRun is true)
• nextActions (only when not dryRun)

Data Model

A todo item has the following shape:

{
  "id": "string",
  "title": "string",
  "description": "string?",
  "completed": false,
  "priority": "low|normal|high",
  "dueDate": "YYYY-MM-DD?",
  "tags": ["string"],
  "createdAt": "ISO timestamp with offset",
  "updatedAt": "ISO timestamp with offset?",
  "completedAt": "ISO timestamp with offset?"
}

Notes:

• dueDate uses YYYY-MM-DD (date only).
• createdAt, updatedAt, and completedAt are ISO 8601 timestamps with offset (e.g., 2025-02-28T10:30:00Z).

Client Configuration

{
  "todokit": {
    "command": "npx",
    "args": ["-y", "@j0hanz/todokit-mcp@latest"]
  }
}

{
  "mcpServers": {
    "todokit": {
      "command": "npx",
      "args": ["-y", "@j0hanz/todokit-mcp@latest"]
    }
  }
}

Development

Prerequisites

• Node.js >= 20.0.0

Scripts

Manual verification

npm run build
npm run inspector -- node dist/index.js

Project structure

src/
  index.ts   # MCP server entrypoint (stdio)
  tools/     # Tool registrations
  schemas/   # Zod input/output schemas
  lib/       # Storage, matching, shared helpers
tests/       # Unit tests
docs/        # Assets (logo)

Contributing

Contributions are welcome. Please run npm run format, npm run lint, npm run type-check, npm run build, npm test, npm run test:coverage, and npm run dup-check before opening a PR.

License

This project is licensed under the MIT License - see the LICENSE file for details.