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

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

Pull requests and pushes to main run these checks with Taskwarrior installed, validate and build the MCPB bundle, and audit the locked dependencies in a separate job. Locally, integration tests are skipped if task is missing; the command diagnostic regression tests still run without it.

Dependency security

bun audit checks development dependencies as well as the server's dependencies. The tmp override selects the patched 0.2.x release for MCPB's older Inquirer / external-editor chain. A packaging-dependency regression test covers temporary file creation, editing, cleanup, and rejection of path traversal in file names. Remove this override once MCPB's dependency chain selects a patched version itself.

As of October 8, 2026, the remaining audit finding is GHSA-86w9-cpqp-85rv in node-forge 1.4.0, used by MCPB's signing and verification tooling. No patched release is available yet. It is not bundled into the stdio server; this does not make the packaging tooling safe for processing untrusted signed bundles. The audit remains enabled and fails on this finding until an upstream fix is released.