The Todokit MCP Server is a task management tool that provides comprehensive CRUD operations for todos with JSON persistence, batch operations, and advanced filtering capabilities.
Core Capabilities:
Create todos - Add single or multiple todo items (up to 50 per batch) with title, description, priority (low/normal/high), tags (up to 50), and due dates (ISO format)
List and filter - Retrieve todos with flexible filtering by status (pending/completed/all), priority, tags, date ranges (dueAfter/dueBefore), and text search across titles, descriptions, and tags
Sorting & pagination - Sort by title, priority, dueDate, or createdAt in ascending/descending order with offset/limit controls (up to 200 results per query, default 50)
Update todos - Modify existing todo fields including title, description, priority, tags, and due dates
Complete todos - Mark tasks as completed or change completion status
Delete todos - Remove individual todos or bulk delete with filters, dry-run preview mode, and safety limits (default 10 items, max 100)
Key Features:
JSON persistence - Configurable storage location via
TODOKIT_TODO_FILEenvironment variable or--todo-fileCLI flag with atomic file writes and automatic cleanup when all todos are completedData validation - Strict input validation using Zod schemas with consistent error response format
Diagnostics - Optional monitoring via
--diagnosticsflag and--log-levelsettings (error/warn/info/debug) with programmatic access through Node.js diagnostics channelsConfiguration options - Customizable JSON formatting (pretty-printed or compact) via
TODOKIT_JSON_PRETTYenvironment variableClient integration - Easy setup for VS Code, Claude Desktop, and Cursor with one-click installation options
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Todokit MCP Serveradd a todo to finish the quarterly report by Friday with high priority"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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, and delete todos.
Batch operations: add multiple todos at once.
Safe listing: status-based filtering with a default of pending-only and truncation to keep responses small.
JSON persistence with queued writes and atomic file writes.
Optional diagnostics events (tool calls/results, storage, lifecycle) via Node diagnostics channels.
Quick Start
The server runs over stdio (no HTTP endpoint) and registers MCP tools on startup.
Installation
NPX (recommended)
Global install
Then run:
From source
Configuration
Storage path
By default, todos are stored in todos.json in the current working directory. 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.
When all todos are completed, the server removes the storage file so it does not linger on disk.
Examples:
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.
CLI options
The server accepts a few CLI flags (use -- to forward args when running via npx).
Flag | Alias | Description |
|
| Override the todo storage path (same as |
|
| Enable diagnostics output (JSON lines) to stderr. |
|
| Diagnostics log level: |
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 eventstodokit:storage— read/write/close eventstodokit: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:
Error payload:
The result shape is tool-specific.
add_todo
Create a new todo item.
Parameter | Type | Required | Description |
description | string | Yes | Description of the todo (1-2000 chars) |
priority | string | Yes | Priority: |
category | string | Yes | Category: |
dueAt | string | No | Optional due date/time as an ISO 8601 timestamp with offset (RFC3339) |
Result fields:
item(todo)summarynextActions
add_todos
Add multiple todo items in one call.
Parameters:
items(array, required): Array of todo objects (1-50 items). Each item supportsdescription,priority,category,dueAt.
Result fields:
items(todos)summarynextActions
list_todos
List todos with an optional status filter.
Parameter | Type | Required | Default | Description |
status | string | No | pending | Filter by status: pending, completed, all |
Notes:
Results may be truncated for safety (currently returns up to 50 items). Use
status: "pending"(default) orstatus: "completed"to narrow the response.
Result fields:
items(todos)summarycounts(total,pending,completed) — global counts across all todosfilteredCounts(total,pending,completed) — counts within the requested status filterstatus(the effective status filter)returned,truncated,remaining,hint
update_todo
Update fields on a todo item.
Parameter | Type | Required | Description |
id | string | Yes | The ID of the todo to update |
description | string | No | New description (1-2000 chars) |
priority | string | No | New priority: |
category | string | No | New category: |
dueAt | string | No | Replace due date/time (ISO 8601 with offset) |
Notes:
If no updatable fields are provided, the tool returns an error.
Result fields:
item(todo)summarynextActions
complete_todo
Mark a todo as completed.
Parameter | Type | Required | Description |
id | string | Yes | The ID of the todo |
Result fields:
item(todo)summarynextActions
delete_todo
Delete a todo item by ID.
Parameter | Type | Required | Description |
id | string | Yes | The ID of the todo to delete |
Result fields:
deletedIds(array)summarynextActions
Data Model
A todo item has the following shape:
Notes:
createdAt,updatedAt, andcompletedAtare ISO 8601 timestamps with offset (e.g.,2025-02-28T10:30:00Z).dueAtuses the same ISO 8601 timestamp format with an explicit offset.When tools report an ambiguous match (error code
E_AMBIGUOUS), prefer using an exactidfrom the provided candidates.
Client Configuration
Add this to your mcpServers configuration in settings.json:
Add this to your claude_desktop_config.json:
Go to Cursor Settings > Features > MCP
Click + Add New MCP Server
Name:
todokitType:
commandCommand:
npx -y @j0hanz/todokit-mcp@latest
Development
Prerequisites
Node.js >= 20.0.0
Scripts
Command | Description |
npm run build | Compile TypeScript to JavaScript |
npm run dev | Run server in watch mode for development |
npm start | Run the built server |
npm run test | Run unit tests (node --test + tsx) |
npm run test:coverage | Run unit tests with coverage |
npm run lint | Run ESLint |
npm run format | Format with Prettier |
npm run format:check | Check formatting with Prettier |
npm run type-check | Run TypeScript type checking |
npm run dup-check | Run duplicate code checks (jscpd) |
npm run clean | Remove the dist/ build output |
npm run inspector | Launch the MCP inspector (pass server cmd after |
Manual verification
Project structure
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.