An AI-native Taskwarrior bridge that provides natural language task management for Claude Code and other AI systems. This MCP (Model Context Protocol) server extends Taskwarrior with context-aware, natural language capabilities while building on top of the existing Taskwarrior infrastructure.

• Natural Language Processing: Convert everyday language into Taskwarrior commands
• Project Context Awareness: Automatically detects current project/ticket context
• Ticket Integration: Sync tasks from ticket checklists (supports .tickets/ directory structure)
• Eisenhower Matrix: Organize tasks by urgency and importance
• Smart Task Addition: Intelligently parse priorities, due dates, projects, and tags
• Shareable & Versioned: Configuration can be tracked in Git

1. Install Taskwarrior (if not already installed):

brew install task

2. Install Node.js (v20 or later):

brew install node

1. Clone the repository:

git clone https://github.com/storypixel/mcp-taskwarrior-ai.git
cd mcp-taskwarrior-ai

2. Install dependencies:

npm install

3. Build the project:

npm run build

Add the server to your Claude Code MCP configuration:

1. Open your Claude Code settings
2. Add to MCP servers:

{
  "mcpServers": {
    "taskwarrior": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/mcp-taskwarrior-ai/dist/index.js"],
      "env": {}
    }
  }
}

Or using the Claude CLI:

claude mcp add taskwarrior -s project -- node /path/to/mcp-taskwarrior-ai/dist/index.js

The bridge understands natural language for task management:

• Adding tasks: "add fix the login bug", "create task for code review", "todo implement caching"
• Listing tasks: "show all tasks", "what should I work on next", "list urgent tasks", "show tasks for today"
• Completing tasks: "mark task 5 as done", "complete task 1", "finish the review task"
• Context queries: "where am I", "what's my current project", "show current context"

Execute Taskwarrior commands using natural language.

{
  query: "add fix the authentication bug with high priority"
}

Add tasks with structured metadata:

{
  description: "Implement user authentication",
  project: "myheb-android",
  priority: "H",
  due: "tomorrow",
  tags: ["security", "auth"]
}

Import tasks from a ticket's checklist:

{
  ticket: "DRX-12345"
}

Get tasks organized by Eisenhower Matrix quadrants.

Get current context and suggested next actions based on project state.

Set the current project/context for all task operations:

{
  context: "DRX-12345"
}

Execute raw Taskwarrior commands for advanced users:

{
  command: "modify 1 priority:H +urgent"
}

The bridge automatically detects project context using:

1. .taskproject file - If present, defines the project name for Taskwarrior
2. Git repository name - Falls back to the repo name from git
3. Directory name - Uses current directory name if not in git

To override project detection, create a .taskproject file:

echo "my-project-name" > .taskproject

This is useful when one workspace manages tasks for another project.

The bridge also detects:

• Current Git branch (for ticket context)
• Task state from .task-state.json
• Ticket tasks from .tickets/<ticket>/mr-checklist.md

┌─────────────────┐
│  Claude Code    │
│   or AI Agent   │
└────────┬────────┘
         │ Natural Language
         ▼
┌─────────────────┐
│  MCP Server     │
│  - NLP Parser   │
│  - Context Mgr  │
└────────┬────────┘
         │ Taskwarrior Commands
         ▼
┌─────────────────┐
│   Taskwarrior   │
│   (task CLI)    │
└─────────────────┘

npm run dev

Run the test script to verify the server is working:

node test.js

npm run build

The server uses your existing Taskwarrior configuration (~/.taskrc). You can customize Taskwarrior settings as usual.

The bridge uses the current working directory and automatically detects project context. No hardcoded paths or specific project names are used.

Place ticket tasks in:

.tickets/
└── DRX-12345/
    ├── context.md       # Ticket context
    └── mr-checklist.md  # Tasks as checklist items

Format for mr-checklist.md:

- [ ] Update unit tests
- [ ] Add documentation
- [ ] Run linting

The server includes built-in prompts:

Get a prioritized plan for the day including today's tasks, urgent items, and recommended next actions.

Organize tasks for the week ahead with active projects overview.

Initialize Taskwarrior:

task version

Ensure you're in a project directory or have .task-state.json in your workspace.

Verify .tickets/<ticket>/mr-checklist.md exists and contains checkbox items.

Contributions are welcome! Please feel free to submit a Pull Request.

MIT

storypixel

Built on top of Taskwarrior - the command-line task management tool.