Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-taskwarrior-ai add fix the login bug"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Taskmaster
Install Taskwarrior (if not already installed):
brew install taskInstall Node.js (v20 or later):
brew install nodeClone the repository:
git clone https://github.com/storypixel/mcp-taskwarrior-ai.git
cd mcp-taskwarrior-aiInstall dependencies:
npm installBuild the project:
npm run buildAdd the server to your Claude Code MCP configuration:
Open your Claude Code settings
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.jsThe 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"
task_naturalExecute Taskwarrior commands using natural language.
{
query: "add fix the authentication bug with high priority"
}task_smart_addAdd tasks with structured metadata:
{
description: "Implement user authentication",
project: "myheb-android",
priority: "H",
due: "tomorrow",
tags: ["security", "auth"]
}task_ticket_syncImport tasks from a ticket's checklist:
{
ticket: "DRX-12345"
}task_eisenhowerGet tasks organized by Eisenhower Matrix quadrants.
task_where_am_iGet current context and suggested next actions based on project state.
task_context_setSet the current project/context for all task operations:
{
context: "DRX-12345"
}task_rawExecute raw Taskwarrior commands for advanced users:
{
command: "modify 1 priority:H +urgent"
}The bridge automatically detects project context using:
.taskproject file - If present, defines the project name for Taskwarrior
Git repository name - Falls back to the repo name from git
Directory name - Uses current directory name if not in git
To override project detection, create a .taskproject file:
echo "my-project-name" > .taskprojectThis 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 devRun the test script to verify the server is working:
node test.jsnpm run buildThe 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 itemsFormat for mr-checklist.md:
- [ ] Update unit tests
- [ ] Add documentation
- [ ] Run lintingThe 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 versionEnsure 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.
Set the current project/context for task operations
| Name | Required | Description | Default |
|---|---|---|---|
| context | Yes | Project or context name (e.g., "myheb-android", "pharmacy", "DRX-12345") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description fails to disclose behavioral traits such as whether the context is ephemeral or persistent, if it overwrites existing context, or any side effects. The brief description carries the full burden but offers insufficient detail.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, completely front-loaded with the core action. It is efficient with no redundancy, though it could arguably include more useful details without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description provides the basic 'what it does' but lacks contextual completeness regarding behavior (e.g., durability, scope, how to revert). It is minimally adequate but has clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing examples in the parameter description. The tool description adds minimal additional meaning (tying to task operations), which is already implied by the tool name and context. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb 'Set' and identifies the resource as 'current project/context for task operations', clearly distinguishing it from sibling tools like task_eisenhower or task_natural which focus on different task operations.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives, nor does it mention prerequisites or context persistence. No usage cues are given beyond the basic action.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get tasks organized by Eisenhower Matrix (Urgent/Important quadrants)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as read-only nature, authentication requirements, or side effects. The agent must infer from 'Get' that it is a read operation, but this is not explicitly confirmed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence that efficiently conveys the tool's purpose. Every word is meaningful, and there is no redundant or extraneous information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of the tool (no parameters, no output schema), the description adequately explains what the tool does. However, it does not describe the return format or any constraints, which might leave minor gaps for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are no parameters in the input schema (100% coverage by default). The description adds no param-specific information because none exist, which is acceptable. Baseline for zero parameters is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Get tasks organized by Eisenhower Matrix (Urgent/Important quadrants)', which specifies the verb (Get), resource (tasks), and organization format. Among sibling tools, no other tool offers this specific matrix view, so it naturally differentiates itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide any guidance on when to use this tool versus alternatives. It lacks explicit context, prerequisites, or examples of appropriate scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute Taskwarrior commands using natural language. Examples: "add fix the login bug", "show tasks for today", "what should I work on next", "mark task 5 as done", "list urgent tasks"
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | Natural language task query or command |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It explains the function and gives examples but does not disclose limitations, error handling, or scope of supported commands.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
One sentence plus examples, front-loaded, no unnecessary words. Every part adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (one parameter, no output schema), the description is mostly complete. It could mention supported command scope, but overall adequate.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%. The description adds useful examples beyond the schema's parameter description, clarifying acceptable input formats.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it executes Taskwarrior commands using natural language. This distinguishes it from sibling tools like task_raw (raw commands) and task_smart_add (AI-aided add).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Examples imply use for natural language queries, but no explicit guidance on when to prefer this tool over siblings or when not to use it. Missing when-to-use and when-not-to-use context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Execute raw Taskwarrior commands for advanced users
| Name | Required | Description | Default |
|---|---|---|---|
| command | Yes | Raw Taskwarrior command (without "task" prefix) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries full burden. It fails to disclose that raw commands can modify or delete data without confirmation, which is critical for an agent to assess risk.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded and contains no fluff. Every word adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Lacks output schema and annotations; description does not explain return format, error handling, or safety implications of raw command execution, making it incomplete for a potentially dangerous tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description covers the parameter completely (100% coverage). The tool description adds no extra meaning beyond stating it executes commands, so baseline score of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool executes raw Taskwarrior commands for advanced users. It is specific enough to differentiate from sibling tools like task_natural or task_smart_add, but could further clarify what 'raw' commands entail.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'for advanced users' implies usage when specialized tools are insufficient, but there is no explicit guidance on when to use or avoid this tool, nor alternatives listed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Add a task with intelligent parsing of priority, due dates, projects, and tags
| Name | Required | Description | Default |
|---|---|---|---|
| description | Yes | Task description | |
| project | No | Project name (optional) | |
| priority | No | Priority: H(igh), M(edium), L(ow) | |
| due | No | Due date (e.g., "today", "tomorrow", "2024-01-15") | |
| tags | No | Tags for the task |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It mentions 'intelligent parsing' but does not explain how parsing works, what happens on conflicts with explicit parameters, or any side effects. The tool's behavior regarding permissions or output is not disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, concise sentence with no superfluous words. It could be more informative but is not verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of intelligent parsing and the lack of output schema, the description omits important details like how to leverage parsing, what the function returns, and error handling. More context is needed for effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for each parameter. The description adds marginal value by hinting at parsing from the description parameter, but does not clarify the interaction between parsed and explicit fields.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Add' and resource 'task', and mentions intelligent parsing of priority, due dates, projects, and tags. However, it does not differentiate from sibling tools like task_natural, which may also parse natural language input.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like task_natural or task_raw. There is no mention of prerequisites, best practices, or contexts to avoid.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Sync tasks from a ticket checklist to Taskwarrior
| Name | Required | Description | Default |
|---|---|---|---|
| ticket | Yes | Ticket ID (e.g., "DRX-12345") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose behavioral traits such as whether it is destructive, requires authentication, or handles duplicate tasks. The description implies reading from an external system and writing to Taskwarrior without further details.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no extraneous words. However, slight structure improvement could be made by adding a brief usage note, but it is already efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple tool with one parameter and no output schema, the description is minimally adequate. It lacks behavioral context but given the low complexity, it covers core functionality.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds no extra meaning beyond the schema's parameter description ('Ticket ID (e.g., "DRX-12345")'). No additional format or validation guidance is provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'sync' and the resource 'tasks from a ticket checklist to Taskwarrior'. It distinguishes from siblings like task_smart_add or task_natural by specifying the source (ticket checklist) and target (Taskwarrior).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus sibling tools (e.g., task_smart_add). Missing context such as prerequisites (e.g., need a valid ticket ID) or scenarios where syncing is preferred over manual creation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get current context and suggested next actions based on project state
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It fails to disclose side effects, return value structure, or what 'current context' entails. The description is too vague to inform behavioral expectations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence, front-loaded with purpose. No wasted words; every part contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema or annotations, the description is too minimal. It does not address what kind of context or suggestions are returned, or how to interpret them.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Zero parameters, schema coverage 100%. Baseline 4 applies; the description adds value by explaining tool output, which is not captured in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Get') and identifies the resource ('current context and suggested next actions'), clearly distinguishing it from sibling tools like 'task_context_set' or 'task_eisenhower'.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives, no mention of prerequisites or conditions. The description does not help an agent choose between this and sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0task_context_settask_eisenhowertask_naturaltask_rawtask_smart_addtask_ticket_synctask_where_am_iScored across 7 tools
Most tools have distinct purposes, but task_natural and task_raw both execute commands, and task_context_set and task_where_am_i both deal with context, creating slight ambiguity.
All tools have a 'task_' prefix, but the verb/noun pattern is inconsistent: mix of verb_noun (context_set, smart_add, ticket_sync), noun (eisenhower), adjective (natural, raw), and phrase (where_am_i).
7 tools is well-scoped for a task management server, covering common operations without being excessive.
Core operations (add, query, context, sync) are covered, but missing dedicated tools for delete/update are offset by natural and raw commands that can handle them.
AI-native task management: list, create, update and archive tasks with rich context for AI agents
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
AI-native Kanban board — connect Claude to claim, work and move your tasks over MCP.
