Taskwarrior

You can run an MCP server that lets AI assistants interact with Taskwarrior, enabling you to list, create, modify, and manage tasks through natural language or scripted prompts. It exposes Taskwarrior’s capabilities to an external controller, supporting multiple output formats and convenient configurations for local or cloud setups.

How to use

You will configure a client to connect to the MCP server using either a local stdio command or a remote endpoint. Once connected, you can ask your assistant to list tasks, add new ones, mark tasks as complete, modify attributes, delete tasks, or retrieve detailed task information. You can also work with projects, tags, and annotations, and apply complex filters to find exactly the tasks you need. For responses, you can choose Markdown or JSON formats to suit your workflow.

How to install

Prerequisites: you need Python 3.10 or higher and Taskwarrior installed and available in your PATH.

Install Taskwarrior on your system using your package manager. Examples:

# macOS
brew install task

# Ubuntu/Debian
sudo apt install taskwarrior

# Fedora
sudo dnf install task

# Arch Linux
sudo pacman -S task

From PyPI (recommended)

Install the MCP server package from PyPI using Python’s package manager.

pip install taskwarrior-mcp

From source

If you prefer to build from source, clone the repository and install in editable mode.

git clone https://github.com/yourusername/taskwarrior-mcp.git
cd taskwarrior-mcp
pip install -e .

Configuration

You configure the MCP client side to know how to start and connect to the MCP server. The following examples show common configurations for Claude Desktop, Claude Code CLI, and an uvx-based setup.

{
  "mcpServers": {
    "taskwarrior": {
      "command": "taskwarrior-mcp"
    }
  }
}

Using uvx (no installation required)

If you use uvx to run the MCP server ad hoc, configure it to start the MCP server via uvx with the taskwarrior-mcp binary.

{
  "mcpServers": {
    "taskwarrior": {
      "command": "uvx",
      "args": ["taskwarrior-mcp"]
    }
  }
}

Available tools

taskwarrior_list

List tasks with optional filtering to show current work items.

taskwarrior_add

Create a new task with specified attributes such as project, tags, and due dates.

taskwarrior_complete

Mark a task as completed by its identifier.

taskwarrior_modify

Modify attributes of an existing task, such as priority or due date.

taskwarrior_delete

Delete a task by its identifier.

taskwarrior_get

Retrieve detailed information about a specific task.

taskwarrior_annotate

Add notes or context to a task.

taskwarrior_start

Mark the start of work on a task.

taskwarrior_stop

Mark the end of work on a task.

taskwarrior_projects

List all projects across tasks.

taskwarrior_tags

List all tags used in tasks.

taskwarrior_undo

Undo the last operation performed.

taskwarrior_summary

Get overall task statistics and metrics.