Taskwarrior MCP

An MCP for Taskwarrior.

Features

• Task creation, modification, and deletion
• Task querying and filtering
• Task dependency management
• Task annotations and notes
• Task recurrence handling
• Real-time task updates
• Smart prompts with autocompletion

Installation

npm install @tfr/taskwarrior-mcp

Usage

With npx

npx taskwarrior-mcp

Config

Notes for Claude Desktop

The way Claude Desktop loads an MCP is by spawning a new process, not a shell process, so it doesn't have any of your env info. If you use something like mise then nothing works and the error messages aren't great.

Some people suggest hardcoding in the paths, which works, I suppose, but I took the fix from here and launch Claude with open -a Claude (hopefully from a terminal profile where you won't regret it).

Add this to your config (claude_desktop_config.json):

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

Testing

To test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

API

Task Operations

• task.create: Create a new task with description, project, tags, priority, and dates
• task.update: Update an existing task's properties
• task.delete: Delete a task by ID
• task.get: Get detailed information about a specific task
• task.list: List tasks with optional filtering

Task Management

• task.start: Start working on a task (starts timer and optionally adds a note)
• task.stop: Stop working on a task (stops timer and optionally adds a note)
• task.complete: Mark a task as complete (optionally with a completion note)
• task.annotate: Add a note or annotation to a task (annotations are timestamped)

Query Operations

• task.query: Execute custom Taskwarrior filter queries
• task.filter: Filter tasks by specific criteria
• task.search: Search tasks by text content

Resources

The Taskwarrior MCP exposes the following resources that can be subscribed to for real-time updates:

Task List Resource

• URI: task:///list
• Description: Lists all active (pending) tasks
• MIME Type: application/json
• Content: Array of task objects with basic task information
• Subscription: Yes - Updates when tasks are created, modified, or deleted
• Example Response:

{
  "contents": [{
    "uri": "task:///list",
    "mimeType": "application/json",
    "text": "[{\"id\": 1, \"description\": \"Implement MCP server\", \"project\": \"development\", \"tags\": [\"backend\", \"mcp\"], \"priority\": \"H\"}]"
  }]
}

Task Detail Resource

• URI Template: task:///task/{id}
• Description: Detailed information about a specific task
• MIME Type: application/json
• Content: Complete task object including all metadata, annotations, and history
• Subscription: Yes - Updates when the specific task is modified
• Example Response:

{
  "contents": [{
    "uri": "task:///task/1",
    "mimeType": "application/json",
    "text": "{\"id\": \"1\", \"description\": \"Implement MCP server\", \"project\": \"development\", \"tags\": [\"backend\", \"mcp\"], \"priority\": \"H\", \"status\": \"pending\", \"annotations\": [], \"entry\": \"2024-03-20T12:00:00Z\", \"modified\": \"2024-03-20T12:00:00Z\"}"
  }]
}

Task Project Resource

• URI Template: task:///project/{name}
• Description: Tasks belonging to a specific project
• MIME Type: application/json
• Content: Array of task objects filtered by project
• Subscription: Yes - Updates when tasks in the project are modified
• Example Response:

{
  "contents": [{
    "uri": "task:///project/development",
    "mimeType": "application/json",
    "text": "[{\"id\": 1, \"description\": \"Implement MCP server\", \"project\": \"development\", \"tags\": [\"backend\", \"mcp\"], \"priority\": \"H\"}]"
  }]
}

Task Tag Resource

• URI Template: task:///tag/{name}
• Description: Tasks with a specific tag
• MIME Type: application/json
• Content: Array of task objects filtered by tag
• Subscription: Yes - Updates when tasks with the tag are modified
• Example Response:

{
  "contents": [{
    "uri": "task:///tag/backend",
    "mimeType": "application/json",
    "text": "[{\"id\": 1, \"description\": \"Implement MCP server\", \"project\": \"development\", \"tags\": [\"backend\", \"mcp\"], \"priority\": \"H\"}]"
  }]
}

Resource Completions

The server supports auto-completion for certain resource fields:

Project Completions

• URI: task:///project/
• Description: Provides fuzzy-matched project suggestions
• Example Request:

{
  "ref": {
    "type": "ref/resource",
    "uri": "task:///project/"
  },
  "argument": {
    "value": "dev"
  }
}

• Example Response:

{
  "completion": {
    "values": ["development", "devops"],
    "total": 2,
    "hasMore": false
  }
}

Tag Completions

• URI: task:///tag/
• Description: Provides fuzzy-matched tag suggestions
• Example Request:

{
  "ref": {
    "type": "ref/resource",
    "uri": "task:///tag/"
  },
  "argument": {
    "value": "back"
  }
}

• Example Response:

{
  "completion": {
    "values": ["backend", "backlog"],
    "total": 2,
    "hasMore": false
  }
}

Features:

• Fuzzy matching for typo tolerance
• Returns all items when input is empty
• Caches results for better performance
• No pagination (returns all matches)

Resource Discovery

The server implements the following MCP endpoints for resource discovery:

• resources/list: Lists all available resources
• resources/read: Reads the contents of a specific resource
• resources/subscribe: Subscribes to updates for a resource
• resources/unsubscribe: Unsubscribes from updates for a resource

Example Messages

// Create Task
{
  "type": "task.create",
  "payload": {
    "description": "Implement MCP server",
    "project": "development",
    "tags": ["backend", "mcp"],
    "priority": "H"
  }
}

// Start Task with Note
{
  "type": "task.start",
  "payload": {
    "id": "123",
    "note": "Starting implementation of the MCP server"
  }
}

// Add Annotation
{
  "type": "task.annotate",
  "payload": {
    "id": "123",
    "note": "Found a bug in the task creation logic",
    "isAnnotation": true
  }
}

// Query Tasks
{
  "type": "task.query",
  "payload": {
    "filter": "project:development +PENDING"
  }
}

License

MIT License - See LICENSE file for details

Prompts

The Taskwarrior MCP provides several smart prompts that help with common task management workflows. All prompts support autocompletion for their arguments.

Available Prompts

• today-project: Get all tasks for a specific project that are scheduled for today

  • Arguments:
    • project: Project name (autocompletes from available projects)

• start-work: Start working on a task and optionally add a focus note

  • Arguments:
    • description: Task description (autocompletes from pending tasks)
    • focus: Optional note about what you're specifically working on

• complete-with-review: Mark a task as complete and add a review note

  • Arguments:
    • description: Task description (autocompletes from pending tasks)
    • accomplished: What was accomplished in this task

• search-notes: Display all annotations for tasks matching a description

  • Arguments:
    • description: Task description to search for (autocompletes from pending tasks)

Autocompletion

The prompts support intelligent autocompletion for their arguments:

• Project names are autocompleted from your existing projects
• Task descriptions are autocompleted from your pending tasks
• All autocompletions support fuzzy matching for easier finding