TaskWarrior MCP Server
Integrates with TaskWarrior, providing tools for task management, GTD workflow, and habit tracking, including creating, modifying, completing, and listing tasks, managing dependencies, and supporting recurring tasks.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
TaskWarrior MCP Server
MCP server that wraps TaskWarrior command-line tool. Provides 27 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 attributesmark_task_done- Complete task by UUIDdelete_task- Delete task by UUIDquery_tasks- Filter and sort tasks with cursor paginationget_server_status- Check runtime, executable, and configurationlist_tasks- Query tasks with filters (status, project, tags, dates)get_task_details- Get single task by UUIDstart_task- Start timer on taskstop_task- Stop timer on taskadd_annotation- Add note to taskremove_annotation- Remove note from task
Dependencies
add_dependency- Make task A depend on task Bremove_dependency- Remove dependency link
GTD Workflow
get_next_actions- Filter actionable tasks by context, energy level, time availablequick_capture- Capture a thought in the inboxprocess_inbox- Page through tasks tagged +inbox for processingprocess_inbox_item- Clarify an item as a next action, project, waiting, someday, reference, or deletionget_task_tree- Navigate project hierarchy with depth and node limitsget_waiting_for- Get delegated/waiting tasks, grouped by blocker/date/projectget_blocked_tasks- Get tasks with unmet dependenciesget_project_status- Project metrics: next actions, completion %, stalenessweekly_review- GTD review data: inbox, completed, stalled projects, habitsget_someday_maybe- Get tasks tagged +someday
Batch Operations
create_project_tree- Create project with multiple tasks and dependencies in one callbatch_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 22+ for runtime (use a supported LTS release)
Bun 1.3+ for development workflows
TaskWarrior installed and available as
task
Install
bun install --frozen-lockfile --ignore-scripts
bun run build
bun run doctordoctor (also node dist/index.js --doctor) checks Node, the Taskwarrior executable,
and configuration readability. It exits with code 1 on failure and gives setup guidance.
It does not export task records, test database integrity, or verify write access.
Install Taskwarrior separately and finish its first-run setup in a terminal.
Use TASK_BIN for a custom executable and TASKRC for a custom configuration;
set them in your MCP client’s env when needed. --help lists CLI options.
Run
bun run startOr 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:packThat produces dist/taskwarrior-mcp.mcpb.
The bundle includes explicit ES module metadata and targets Node 22 or newer. Node 18 and 20 are no longer supported.
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 registered tools advertise an output schema and return structuredContent:
{
"structuredContent": {
"status": "success",
"data": { "tasks": [], "page": { "total": 0, "returned": 0, "has_more": false } }
},
"content": [{ "type": "text", "text": "{\"tasks\":[],\"page\":{\"total\":0,\"returned\":0,\"has_more\":false}}" }]
}data contains the tool's task, array, or report. Legacy text payloads remain available;
legacy mutation envelopes are unwrapped in structured data. Execution failures set
MCP isError:true, status:"error", and error:{code,message}. Partial operations
retain their progress in data; inspect it before retrying. Invalid MCP inputs are
reported by the SDK before execution.
GTD tools return enriched responses with:
tasks- Array of task objectsmetadata- Counts (total, actionable, blocked, waiting, completed)insights- Summary, recommendations, warningsgroups- Tasks grouped by project/context/frequencyrelationships- Dependency chains (where applicable)
GTD Features
Capture, clarify, and act
Call
quick_capturewith{"description":"Think about proposal"}.Use its returned UUID in
process_inbox_item:{"uuid":"<UUID>","action":"next_action","description":"Draft proposal outline","context":"@work","estimated_minutes":15}.Call
get_next_actionswith{"context":"@work","max_minutes":15}.
Clarification preserves unrelated tags and removes inbox and incompatible workflow
tags. project requires a project name and turns the existing item into a project root;
create_project_tree creates a new root with children and dependencies. someday and
reference remain stored but are excluded from next actions. delete marks the item
deleted. An optional note adds an annotation after classification; a failure reports
that classification already succeeded.
Delegate with process_inbox_item using
{"uuid":"<UUID>","action":"waiting","waiting_for":"Alex","follow_up":"tomorrow"}.
waiting_for records the person or external factor; follow_up is the reminder date.
Passing that date never makes the task actionable automatically. get_waiting_for
supports recipient/project filters and follow_up_due:true; weekly_review includes
groups.follow_ups_due. Clarify as next_action to clear delegation, or explicitly
clear waiting_for and follow_up with modify_task. Native wait still means defer
until a date and is separate from delegation.
Queries and project navigation
query_tasks accepts status, project, tags, dates, context, priority, waiting_for,
parent, active, and blocked filters. Project filters include subprojects. Sort by
urgency (default descending), configured priority (default highest first), due, entry,
modified, description, or project. sort_order can be asc or desc; missing values
come last and UUID breaks ties. list_tasks retains its raw-array interface.
query_tasks, process_inbox, and get_next_actions return page with total,
returned, has_more, and optional next_cursor. The default page size is 50, with
limit from 1 to 200. Repeat the same filters with cursor: next_cursor for the next
page. Changed results or filters invalidate the cursor: restart without it. These
queries bound returned records but still read matching data to calculate totals;
they are not database snapshots. Groupings and insights describe the returned page
unless noted otherwise; inbox processing insights cover the whole inbox.
Call get_task_tree with {"project":"Launch"} or {"uuid":"<ROOT_UUID>"}.
Nodes contain the task, depth, child UUIDs, and unresolved dependency UUIDs. Counts
apply to returned nodes, including completed/deleted history. Default limits are
depth:10 and max_nodes:200 (maximum 100 and 500). If metadata.truncated is true,
continue from a child UUID. Cycles and missing/out-of-scope parents produce warnings.
Project hierarchy uses mcp_parent, independently of recurrence.
Task Fields
estimated_minutes- Explicit integer duration estimate, from 0 to 525600 minuteswaiting_for- Delegation recipient or external factorfollow_up- Date to review a delegated taskscheduled- Date to start workwait- Hide until date (deferred)until- Task expires after datecontext- GTD context (@home, @work, @phone)energy- Energy level required (H/M/L)depends- Array of task UUIDs this depends onparent(write requests) - Project parent UUID, stored as themcp_parentuser-defined attribute. Taskwarrior’s exportedparentfield is reserved for recurrence templates.recur- Recurrence pattern (daily, weekly, monthly, etc.)tags- Unicode letters, combining marks, digits,_and-. Tag writes use Taskwarrior'stags:attribute and tag filters usetags.has:, because the+tagshorthand 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 a template task (status:recurring) that generates instances.
get_recurring_tasks calculates statistics from exported instances and their due dates,
not the template mask. Future unfinished instances do not reduce completion rates or
break streaks. An unfinished or deleted occurrence counts as missed once its due time
passes. Completed occurrences count even when completed early. total_instances
includes future occurrences; evaluated_instances is the completion-rate denominator.
Averages include only habits with evaluated occurrences. Missing/purged history cannot be reconstructed. include_completed:true additionally
includes completed templates; ordinary completed instances remain statistics, not templates.
Configuration and write behavior
context, energy, waiting_for, and mcp_parent are string user-defined attributes
(UDAs); estimated_minutes is numeric and follow_up is a date.
The server supplies their type definitions as command-local overrides, so fresh
Taskwarrior installations store them correctly without changing your taskrc.
Other UDA settings, including configured allowed values, still apply. Energy filters
use H, M, and L. To display these fields in your own CLI reports, add the same
UDA definitions to your taskrc and configure the report columns:
uda.context.type=string
uda.energy.type=string
uda.mcp_parent.type=string
uda.estimated_minutes.type=numeric
uda.waiting_for.type=string
uda.follow_up.type=dateUse an empty string in modify_task or batch_modify_tasks to clear dates,
context, energy, project, priority, parent, waiting_for, or follow_up. Use
estimated_minutes:null to clear the estimate. Batch edits accept the same fields as
individual edits, including dependency changes and parent. Omitted fields remain unchanged. Taskwarrior validates
field combinations; a failed dependency replacement does not apply the other
modifications in that same command.
Project creation validates dependency indices and cycles before writing. It uses
UUID output, so verbose=nothing works. Project and batch operations are not
transactions: failures return MCP isError:true and identify completed work where
available. Inspect returned UUIDs before retrying; do not blindly recreate tasks.
The project root uses project_root, and children use mcp_parent, leaving native
recurrence relationships intact.
Tool calls are serialized within one server to prevent its read-modify-write
operations from interleaving. Other Taskwarrior processes can still edit the same
records concurrently. Subprocesses run without a shell, asynchronously, with closed
stdin, a 10 MiB output limit and a 30-second timeout. Set TASK_TIMEOUT_MS to an
integer from 1 to 300000 to adjust the timeout. Interactive confirmations are not
possible; delete_task supports skipConfirmation:true for an authorized deletion.
The stdio transport caps buffered input at 1 MiB; validation also caps combined input elements at 25,000 and the server queues at most 100 tool calls. Task contents and full command arguments are not routinely logged. Export validation returns an error for malformed records rather than silently omitting tasks. Existing Unicode projects/tags and custom priority values are preserved in exports. Writes accept Unicode letters/digits/combining marks in projects and tags; project names additionally allow spaces and dots. Custom priority identifiers are passed to Taskwarrior for validation against its configured values.
Next-action and project/weekly-review counts exclude future scheduled/waiting tasks,
inbox/reference/someday items, project roots, delegated tasks, and unresolved dependencies. Completed/deleted
dependencies do not block tasks. Time filtering uses estimated_minutes, falling back to legacy numeric complexity
values in minutes. max_minutes takes precedence over time_available. Unknown
estimates are excluded when a time filter is set unless include_unestimated:true.
Urgency is not treated as a duration estimate.
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 buildPull requests and pushes to main run these checks with Taskwarrior installed,
validate and build the MCPB bundle, then run the stdio schema and task-operation
smoke test against its extracted entry point on Node 24.22.1 and Node 22
on Linux. Build and lint tooling stay on Node 24. Dependencies are audited in a
separate job. Locally, integration tests are skipped if task is missing; the command
diagnostic regression tests still run without it.
Dependency security
Before installing dependencies, review package.json, bun.lock, registry metadata,
and current advisories. Use bun install --frozen-lockfile --ignore-scripts; builds
are explicit commands. Integrity hashes establish artifact consistency, not trust
in package contents.
bun audit checks development dependencies as well as the server's dependencies.
The full audit is clean after the November 9, 2026 tooling migration; the CI audit
remains enabled with no advisory suppressions.
Packaging uses scripts/mcpb.mjs, the vendored official MCPB 0.3 JSON schema, Ajv,
and fflate. It produces the same four-file Node bundle without installing the
MCPB CLI and its vulnerable Zod 3 dependency chain. It validates the manifest,
launch configuration, ESM metadata, and explicit file allowlist. See
tooling security notes for review and compatibility evidence.
The exact minimatch 11.0.1 override fixes its glob-expansion advisory. This is a reviewed major-version exception for ESLint/TypeScript ESLint's actual matching APIs; regression tests check file selection, ignored output, type-aware rules, and bounded adversarial expansion. Remove the override when upstream dependency ranges accept a patched release. No global Zod override is used.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
ADHD-friendly task management MCP server for ChaTodo: organize tasks, lists, and priorities.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Local-first task manager: create, edit, and complete tasks, projects, and checklists via MCP.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to interact with the Taskwarrior command-line task management tool. It allows users to list, create, modify, and organize tasks using projects, tags, and annotations through natural language.132MIT
- FlicenseNot gradedqualityDmaintenanceRemote MCP server for managing TickTick tasks and projects, offering 22 tools for CRUD, search, and GTD workflows via any MCP client.1-
- AlicenseAqualityCmaintenanceMCP server for Taskwarrior 3.x — 35 tools for task lifecycle, time tracking, schema validation, and role-based permissions.3542 PyPI3Apache 2.0
- AlicenseNot gradedqualityDmaintenanceAn MCP server that wraps the Taskwarrior CLI to allow AI assistants to create, query, modify, and manage tasks directly from agentic coding tools.11 npmMIT