taskwarrior

This MCP server wraps the TaskWarrior command-line tool and exposes 22 tools for managing tasks, GTD workflows, and habit tracking. After starting the server, you can use the provided tools to create, modify, query, and organize tasks, as well as manage dependencies, annotations, and recurring tasks. The server supports GTD operations such as getting next actions, processing inbox items, and reviewing waiting or blocked tasks, making it a convenient backend for TaskWarrior-based workflows. Typical usage involves sending requests to the MCP server for operations like adding a task, querying tasks with filters, or generating GTD insights; responses follow the MCP standard format described in the project docs and include enriched data when using GTD tools.

You’ll find tools categorized under Basic Task Operations, Dependencies, GTD Workflow, Batch Operations, and Habits/Recurring Tasks. For example, add_task creates a new task with optional GTD fields (context, energy, scheduled, wait, depends) and supports recurring tasks (recur). get_next_actions returns actionable tasks filtered by context and energy, while get_project_status provides metrics such as next actions and completion percentage. Recurring tasks can be tracked with get_recurring_tasks, which reports completion stats and streaks. The batch tools allow creating a project tree or applying the same modification to multiple tasks in a single call. To work with habits, recurring tasks can be defined with a recur pattern and due date to generate regular task instances.

Use the MCP client configuration example to wire this server into your MCP-enabled client. The server expects the underlying TaskWarrior binary to be available on the host as task, and will invoke TaskWarrior commands as part of each tool’s operation.

Prerequisites

• Node.js 18+ (or Bun-enabled environment as shown in the repo)
• Bun 1.3+ (for development workflows)
• TaskWarrior installed and accessible as task on the host

Install and build

1. Clone the repository: git clone <repository-url> cd <repository-directory>

2. Install dependencies and build the MCP server: bun install bun run build

3. (Optional) Run tests to verify integration with a disposable TaskWarrior setup: bun run test

4. Start the MCP server (examples may vary depending on your setup): bun run start

5. If using Claude Desktop Bundle, validate and package the MCP manifest: bun run mcpb:validate bun run mcpb:pack

6. Update the MCP client configuration to point to the local server (see mcp_config example): { "mcpServers": { "taskwarrior": { "command": "node", "args": ["/path/to/taskwarrior-mcp/dist/index.js"] } } }

Notes and tips:

• This MCP server relies on TaskWarrior being installed on the host and available as the task binary. If your setup uses non-default paths, configure TASK_BIN or TASKRC via environment variables or MCPB manifest options as described in the repository.
• The Claude Desktop Bundle integration exposes optional TASK_BIN and TASKRC settings for non-default TaskWarrior configurations.
• When deploying, ensure that the host has appropriate permissions for TaskWarrior operations and that the MCP server can invoke task appropriately.
• Environment variables you might encounter or need: TASKRC (path to TaskWarrior rc file), TASK_BIN (path to TaskWarrior binary). These can influence how TaskWarrior is located and executed by the MCP server.
• If you run into path issues, verify that the build output index.js path matches the configured mcpServers entry and that the dist/index.js file exports the expected MCP server interface.
• For best results, keep TaskWarrior up to date and aligned with your workflow needs (contexts, projects, and habit definitions) to maximize GTD tooling usefulness.