A MCP server for Todokit, a task management and productivity tool with JSON storage.
npm install @j0hanz/todokit-mcp 

An MCP server for Todokit, a task management and productivity tool with JSON storage.
Todokit MCP provides a lightweight, local task management system that integrates directly with your AI coding assistant. It uses a simple JSON file for persistence, allowing you to create, track, and complete tasks without leaving your editor. The server automatically handles file safety, locking, and atomic writes.
- Local Persistence: Stores tasks in a human-readable todos.json file in your working directory.
- Task Management: Create, update, complete, and delete tasks with priorities and categories.
- Batch Operations: Add multiple tasks efficiently in a single operation.
- Filtering: List tasks by status (pending/completed) to keep context manageable.
- Safety Controls: Validates file paths to prevent traversal outside the working directory (unless configured).
- Diagnostics: emitting events for tool calls, storage operations, and lifecycle events.
- Runtime: Node.js >=22.19.8
- Language: TypeScript 5.9
- SDK: Model Context Protocol SDK (@modelcontextprotocol/sdk)
- Libraries: Zod (validation)
``text`
c:\todokit-mcp
├── dist/ # Compiled output
├── scripts/ # Build and task scripts
├── src/
│ ├── index.ts # Server entrypoint & startup
│ ├── schema.ts # Zod schemas for tools & types
│ ├── storage.ts # JSON file persistence layer
│ └── tools.ts # Tool registration & handlers
├── package.json
└── README.md
- Node.js >=22.19.8
`bash`
npx -y @j0hanz/todokit-mcp@latest
The server can be configured via CLI arguments or environment variables.
| Flag | Short | Description |
| --------------- | ----- | ------------------------------------------------------------------ |
| --todo-file | -f | Path to the todo JSON file. |--diagnostics
| | -d | Enable diagnostic logging to stderr. |--log-level
| | -l | Set log level (error, warn, info, debug). Default: info. |
| Variable | Description | Default |
| ----------------------------- | --------------------------------------------------------------- | --------------------- |
| TODOKIT_TODO_FILE | Absolute or relative path to the todo storage file. | todos.json (in CWD) |TODOKIT_JSON_PRETTY
| | Set to true or 1 to indent JSON files with 2 spaces. | false (compact) |TODOKIT_TOOL_TIMEOUT_MS
| | Timeout for tool execution in milliseconds. | 60000 |TODOKIT_LOCK_TIMEOUT_MS
| | Timeout for acquiring file lock. | 5000 |TODOKIT_MAX_TODO_FILE_BYTES
| | Maximum allowed size of the todo file. | 5242880 (5MB) |TODOKIT_ALLOW_OUTSIDE_CWD
| | Allow storage file to be outside the current working directory. | false |
| Tool | Description | Parameters | Results |
| --------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
| add_todo | Create a new task. | description (str, req), priority (enum, req), category (enum, req), dueAt (iso-date, opt) | Returns the created item and summary. |add_todos
| | Create multiple tasks in batch. | items (array of todos, req, max 50) | Returns count and IDs of created items. |list_todos
| | List tasks with optional filtering. | status (pending/completed/all, opt, def: pending) | Returns list of items, counts, and status summary. |update_todo
| | Update an existing task. | id (str, req), description, priority, category, dueAt (all opt) | Returns updated item. |complete_todo
| | Mark a task as completed. | id (str, req) | Returns updated item. |delete_todo
| | Permanently remove a task. | id (str, req) | Returns summary of deletion. |
| URI Template | Type | Description |
| ------------------------- | --------------- | ----------------------------------------------------------------- |
| internal://instructions | text/markdown | Returns usage instructions and context about the Todokit manager. |
VS Code
Add to your settings.json (Code) or mcpServers configuration:
`json`
{
"todokit": {
"command": "npx",
"args": ["-y", "@j0hanz/todokit-mcp@latest"]
}
}
Claude Desktop
Add to claude_desktop_config.json:
`json`
{
"mcpServers": {
"todokit": {
"command": "npx",
"args": ["-y", "@j0hanz/todokit-mcp@latest"]
}
}
}
Cursor
1. Open Cursor Settings > Features > MCP
2. Click + Add New MCP Server
3. Name: todokitcommand
4. Type: npx -y @j0hanz/todokit-mcp@latest
5. Command:
- Path Traversal: By default, the server enforces that the todos.json file must reside within the current working directory. You must explicitly opt-in via TODOKIT_ALLOW_OUTSIDE_CWD to store files elsewhere.
- File Limits: The server enforces a maximum file size (default 5MB) to prevent disk exhaustion.
1. Install Dependencies
`bash`
npm install
2. Common Scripts
| Script | Description |
| ------------------- | ----------------------------------------- |
| npm run build | Builds the project to dist/. |npm run dev
| | Watches for changes and recompiles. |npm run test
| | Runs the test suite via Node test runner. |npm run lint
| | Lints code with ESLint. |npm run format
| | Formats code with Prettier. |npm run inspector
| | Launches the MCP inspector for debugging. |
- Server Error: Server not initialized: This typically happens if tools are called before the server has fully started. Ensure the client waits for initialization.
- Storage Error: path outside CWD: You are trying to use a file outside the workspace. Move the file or set TODOKIT_ALLOW_OUTSIDE_CWD=1`.
MIT