todokit-mcp

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 in one call.
• 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 delete returns previews for ambiguous matches.
• JSON persistence with caching and atomic writes.

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

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.

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

Tools

All tools return a JSON payload in both content (stringified) and structuredContent with the shape:

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

When an error occurs, ok is false and error contains { code, message }.The result shape is tool-specific.If a query matches multiple todos, tools return E_AMBIGUOUS with previews and a hint to use an exact id.

add_todo

Add a new todo item.

add_todos

Add multiple todo items in one call.

list_todos

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

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.

complete_todo

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

delete_todo

Delete a todo item. Provide either id or query.

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",
  "updatedAt": "ISO timestamp?",
  "completedAt": "ISO timestamp?"
}

Client Configuration

Add this to your mcpServers configuration in settings.json:

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

Add this to your claude_desktop_config.json:

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

1. Go to Cursor Settings > Features > MCP
2. Click + Add New MCP Server
3. Name: todokit
4. Type: command
5. Command: npx -y @j0hanz/todokit-mcp@latest

Development

Prerequisites

• Node.js >= 20.0.0

Scripts

Manual verification

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Project structure

src/index.ts # MCP server entrypoint (stdio)tools/ # Tool registrationsschemas/ # Zod input/output schemaslib/ # Storage, matching, shared helpers

Contributing

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

License

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