kloner-tasks-mcp

kloner-tasks-mcp

MCP server for managing Kloner Tasks from Cursor, Claude Code, or any MCP-compatible client.

Quick Start

1. Install the Cursor rule (recommended)

npx -y kloner-tasks-mcp --install-rule

This installs a Cursor rule that teaches the AI how to create tasks, log time, and track progress. Task creation is off by default — see Per-Project Toggle below.

2. Add the MCP server to Cursor

Paste this into Cursor MCP settings (Settings → MCP → + Add):

{
  "mcpServers": {
    "kloner-tasks": {
      "command": "npx",
      "args": ["-y", "kloner-tasks-mcp"],
      "env": {
        "KLONER_API_URL": "https://tasks.kloner.com",
        "KLONER_API_KEY": "your-api-key-here"
      }
    }
  }
}

3. Restart Cursor

Done. You can now ask the AI to track tasks (e.g. "track this"), or enable auto-tracking per project.

Claude Code

Add to your project's .mcp.json:

{
  "mcpServers": {
    "kloner-tasks": {
      "command": "npx",
      "args": ["-y", "kloner-tasks-mcp"],
      "env": {
        "KLONER_API_URL": "https://tasks.kloner.com",
        "KLONER_API_KEY": "your-api-key-here"
      }
    }
  }
}

For the agent rule, paste the contents of examples/agents-section.md into your project's AGENTS.md.

Per-Project Toggle

By default, the AI will not auto-create tasks. To enable automatic task tracking for a specific project, add this to the project's .env.local:

KLONER_AUTO_TASKS=true

Value	Behavior
true	Auto-create a task for every meaningful coding objective
false or not set	Only create tasks when you explicitly ask (e.g. "track this")

You can always override per-session by saying "track this" or "don't track this".

Environment Variables

Variable	Required	Where	Description
KLONER_API_KEY	Yes	MCP server env	API key from Kloner Tasks
KLONER_API_URL	No	MCP server env	API base URL (default: https://tasks.kloner.com)
KLONER_DEFAULT_PROJECT_ID	No	MCP server env	Default project ID — skips needing list_projects every time
KLONER_DEFAULT_LIST_ID	No	MCP server env	Default list ID for task creation
KLONER_ASSIGNEE_ID	No	MCP server env	Auto-assign new tasks to this user ID
KLONER_AUTO_TASKS	No	Project .env.local	Enable automatic task creation (true/false)

You can discover project, list, and member IDs by calling the list_projects and list_members tools after setup.

Available Tools (20)

Tool	Description
list_projects	List all projects with their lists
list_members	List workspace members
create_list	Create a new list in a project
create_task	Create a task
create_subtask	Create a subtask under a parent task
get_task	Get task details by ID
list_tasks	List/search tasks with filters
update_task	Update task fields
complete_task	Mark a task as DONE
delete_task	Soft-delete a task
add_comment	Add a comment to a task
list_comments	List comments on a task
log_time	Log time spent on a task
list_time_entries	List time entries
delete_time_entry	Delete a time entry
update_time_entry	Update a time entry
log_ai_usage	Log AI token usage against a task
list_ai_usage	List AI usage entries
get_ai_usage_summary	Get aggregated AI usage/cost summary
view_tasks	Interactive task list UI (MCP Apps)

Development

git clone <repo-url>
cd kloner-tasks-mcp
npm install
npm run dev

Build

npm run build        # compile TypeScript + bundle UI
npm run build:ui     # bundle the MCP Apps UI only

Architecture

File	Role
src/index.ts	MCP server — tool registration, Zod schemas, formatting
src/api.ts	HTTP client — one function per API endpoint
src/views/	MCP Apps UI (interactive task list)
examples/cursor-rule.mdc	Cursor rule for automatic task tracking
examples/agents-section.md	Claude Code AGENTS.md snippet