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 |