An MCP for Taskwarrior.

• 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

npm install @tfr/taskwarrior-mcp

npx taskwarrior-mcp

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"
      ]
    }
  }
}

To test the server using the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/index.js

• 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.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)

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

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

• 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\"}]"
  }]
}

• 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\"}"
  }]
}

• 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\"}]"
  }]
}

• 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\"}]"
  }]
}

The server supports auto-completion for certain resource fields:

• 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
  }
}

• 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)

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

// 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"
  }
}

MIT License - See LICENSE file for details

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

• 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)

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