questlog-mcp

An MCP server that exposes Taskwarrior task management to AI assistants and agentic coding tools. It wraps the task CLI and surfaces a set of structured tools for creating, querying, modifying, and managing tasks directly from your AI coding environment.

Requirements

• Taskwarrior v3.x (v2 is not supported)
• Node.js v18 or later

Install Taskwarrior

macOS (Homebrew):

brew install task

Linux (apt):

sudo apt install taskwarrior

Verify the installation and confirm you are on version 3:

task --version

Tools

| Tool | Description | | --------------- | --------------------------------------------------------------------------- | | task_list | List tasks with an optional Taskwarrior filter string | | task_get | Get a single task by its numeric ID | | task_add | Add a new task with optional project, priority, tags, and due date | | task_bulk_add | Add multiple tasks at once | | task_complete | Mark a task as complete by ID | | task_modify | Modify an existing task's description, project, priority, tags, or due date | | task_delete | Delete a task by ID | | task_annotate | Add an annotation (note) to a task | | task_summary | Get a high-level summary of all tasks with counts and a project breakdown | | task_start | Start time tracking on a task | | task_stop | Stop time tracking on a task |

Tool Details

task_list

Lists tasks. Accepts an optional filter string using standard Taskwarrior filter syntax.

filter: "project:work status:pending"
filter: "priority:H due:today"
filter: "+home"

task_get

Returns a single task by its numeric ID.

id: 42

task_add

Creates a new task. Only description is required.

description: "Write release notes"
project: "work"
priority: "H"   // H, M, or L
tags: ["docs", "release"]
due: "2024-12-31"

task_bulk_add

Creates multiple tasks in a single call. Accepts an array of task objects with the same fields as task_add. Requires at least one task.

tasks: [
  { description: "Set up CI", project: "infra", priority: "H" },
  { description: "Write tests", project: "infra", tags: ["testing"] },
  { description: "Update docs", due: "2024-12-31" }
]

task_complete

Marks a task done by ID.

id: 7

task_modify

Updates fields on an existing task. All fields except id are optional. Tags can be added or removed independently.

id: 7
description: "Updated description"
project: "personal"
priority: "L"
tags: { add: ["urgent"], remove: ["waiting"] }
due: "2025-01-15"

task_delete

Deletes a task by ID.

id: 7

task_annotate

Attaches a note to an existing task.

id: 7
annotation: "Blocked on review from Alice"

task_summary

Takes no arguments. Returns task counts by status and a breakdown by project.

task_start / task_stop

Start or stop active time tracking on a task by ID.

id: 7

MCP Configuration

The server communicates over stdio using the MCP protocol and can be run directly via npx — no installation or cloning required.

Claude Desktop

Add the following to your Claude Desktop config file.

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
    "mcpServers": {
        "questlog": {
            "command": "npx",
            "args": ["-y", "questlog-mcp"]
        }
    }
}

Claude Code (CLI)

claude mcp add questlog -- npx -y questlog-mcp

Cursor

Open Cursor settings, navigate to the MCP section, and add a new server entry:

{
    "questlog": {
        "command": "npx",
        "args": ["-y", "questlog-mcp"]
    }
}

Windsurf

Add the server to your Windsurf MCP config at ~/.codeium/windsurf/mcp_config.json:

{
    "mcpServers": {
        "questlog": {
            "command": "npx",
            "args": ["-y", "questlog-mcp"]
        }
    }
}

VS Code (Continue)

Add the server to your Continue config.json:

{
    "mcpServers": [
        {
            "name": "questlog",
            "command": "npx",
            "args": ["-y", "questlog-mcp"]
        }
    ]
}

Development

Clone the repository and install dependencies:

git clone https://github.com/joeymckenzie/taskwarrior-mcp.git
cd taskwarrior-mcp
bun install

Run the type checker and linter:

bun run types:check
bun run lint

Run the test suite:

bun test

Build the distributable:

bun run build

Note: Bun v1.0 or later is required for development. End users running via npx only need Node.js.

License

MIT