TaskWarrior MCP Server

MCP server that wraps TaskWarrior command-line tool. Provides 22 tools for task management, GTD workflow, and habit tracking.

Tools

Basic Task Operations

• add_task - Create task. Supports GTD fields (context, energy, scheduled, wait, depends) and recurring tasks (recur)

• modify_task - Update task attributes

• mark_task_done - Complete task by UUID

• delete_task - Delete task by UUID

• list_tasks - Query tasks with filters (status, project, tags, dates)

• get_task_details - Get single task by UUID

• start_task - Start timer on task

• stop_task - Stop timer on task

• add_annotation - Add note to task

• remove_annotation - Remove note from task

Dependencies

• add_dependency - Make task A depend on task B

• remove_dependency - Remove dependency link

GTD Workflow

• get_next_actions - Filter actionable tasks by context, energy level, time available

• process_inbox - Get tasks tagged +inbox for processing

• get_waiting_for - Get delegated/waiting tasks, grouped by blocker/date/project

• get_blocked_tasks - Get tasks with unmet dependencies

• get_project_status - Project metrics: next actions, completion %, staleness

• weekly_review - GTD review data: inbox, completed, stalled projects, habits

• get_someday_maybe - Get tasks tagged +someday

Batch Operations

• create_project_tree - Create project with multiple tasks and dependencies in one call

• batch_modify_tasks - Apply same modifications to multiple tasks

Habits/Recurring Tasks

• get_recurring_tasks - Get recurring tasks with completion stats, streaks, frequency

Related MCP server: TickTick MCP Server

Requirements

• Node.js 18+ for runtime

• Bun 1.3+ for development workflows

• TaskWarrior installed and available as task

Install

bun install
bun run build

Run

bun run start

Or configure in your MCP client settings:

{
  "mcpServers": {
    "taskwarrior": {
      "command": "node",
      "args": ["/path/to/taskwarrior-mcp/dist/index.js"]
    }
  }
}

Claude Desktop Bundle

This repo now includes an MCPB manifest for Claude Desktop.

bun run mcpb:validate
bun run mcpb:pack

That produces dist/taskwarrior-mcp.mcpb.

The bundle packages the MCP server, but it does not bundle TaskWarrior itself. Users still need task installed on the host machine. For non-default setups, the MCPB manifest exposes optional TASK_BIN and TASKRC settings.

Response Format

All tools return MCP standard format:

{
  "content": [
    {
      "type": "text",
      "text": "{\"tasks\": [...], \"metadata\": {...}, \"insights\": {...}}"
    }
  ]
}

GTD tools return enriched responses with:

• tasks - Array of task objects

• metadata - Counts (total, actionable, blocked, waiting, completed)

• insights - Summary, recommendations, warnings

• groups - Tasks grouped by project/context/frequency

• relationships - Dependency chains (where applicable)

GTD Features

Task Fields

• scheduled - Date to start work

• wait - Hide until date (deferred)

• until - Task expires after date

• context - GTD context (@home, @work, @phone)

• energy - Energy level required (H/M/L)

• depends - Array of task UUIDs this depends on

• parent - Parent task UUID

• recur - Recurrence pattern (daily, weekly, monthly, etc.)

• tags - Letters, digits, _ and -. Tag writes use Taskwarrior's tags: attribute and tag filters use tags.has:, because the +tag shorthand rejects hyphens and silently rewrites the description instead.

Recurring Tasks

Set recur with due to create habits:

{
  "description": "Take vitamins",
  "recur": "daily",
  "due": "today",
  "context": "@morning"
}

TaskWarrior creates template task (status:recurring) that generates instances. Use get_recurring_tasks to see completion rates and streaks.

Development

bun run typecheck  # Type check source
bun run lint       # Lint source
bun run test       # Run integration tests against disposable Taskwarrior data
bun run build      # Build dist/
bun run check      # Run typecheck, lint, tests, and build