Taskwarrior MCP
While the server is built around Taskwarrior (a different product from the Task/taskfile.dev service listed), it manages a shared task ledger: creating, listing, and fetching tasks; updating fields, statuses, and notes; and coordinating parallel agents through claims, leases, lane handoffs, and takeovers, with project scoping derived from a workspace folder.
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., "@Taskwarrior MCP Show context for this project and claim the next unclaimed task."
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.
Taskwarrior MCP
An MCP server that gives coding agents one shared Taskwarrior ledger. It picks the project from the folder the agent is working in, gives every task a short id, and lets parallel agents claim tasks and hand them over without editing each other's work.
scope acme.api (from session folder) · 6 open · 2 claimed · 1 blocked · 1 waiting on owner · 0 stale >60d
you: no operator lane (opencode-laptop-ses_0001)
CLAIMED BY OTHERS (do not change without a handoff):
7a6f65d2 H bug Login fails when the session cookie has expired [claimed: AcmeProjects/Operator_2, 30m left]
4cc2f1bd H feature Rate-limit the CSV export endpoint [claimed: AcmeProjects/Operator_1, 30m left]
NEXT:
b63f4002 M followup Remove the v1 auth shim after the mobile release
d7edb42d L feature Add OpenAPI examples for the orders endpoints
BLOCKED:
c06a60ad M feature Switch billing webhooks to the new provider [blocked by b63f4002]
WAITING ON OWNER:
7d7eb526 M admin Rotate the staging database password [waiting on owner approval]That is what an agent sees for ~/projects/AcmeProjects/api. With the OpenCode plugin the block is in every session automatically; other clients call task_context.
Why
Agents keep losing track of work that spans sessions. Built-in todo lists disappear when the session ends. A plain task tool lets the model invent project names and task ids, so the same project ends up under five spellings and updates go to ids that don't exist. When several agents run at once, two of them pick up the same task.
This server keeps one Taskwarrior ledger and removes the guesswork:
Project from the folder. A session in
~/projects/AcmeProjects/apiworks in projectacme.api. Agents don't type project names, and near-misses (acme.apii, a path instead of a name) are refused with the closest existing project.Short ids. Every reply uses the first 8 characters of the task UUID. A string that isn't an id is refused instead of matched loosely.
Claims with leases. Updating a task claims it for 30 minutes (longer on request). Another agent's change is refused with who holds it and for how long. Claim checks and writes are serialized across server processes with a lock file.
Lanes and handoffs. Agents running in
<Job>/Operators/Operator_Nfolders act as named lanes. A lane can hand a task to another lane; it moves only when the receiver accepts. A takeover needs a written reason, recorded on the task.Small replies. Writes return one line (
ok 7a6f65d2 done). The context view above is about 200 tokens and stays short as the ledger grows (each section lists a few tasks and counts the rest).Six tools.
task_context,task_list,task_get,task_create,task_update,task_claim.
Related MCP server: cc-handoff
Requirements
Taskwarrior 2.6 or 3.x (tested with 2.6.2 and 3.5.0)
Node.js 20 or newer
Linux (tested). macOS should work but is untested; Windows is not supported.
Install
git clone https://github.com/alessai/Taskwarrior-MCP.git
cd Taskwarrior-MCP
npm install # also builds dist/
npm link # puts `taskwarrior-mcp` on your PATHThe server uses your normal Taskwarrior configuration (~/.taskrc, TASKRC, TASKDATA). It declares the extra fields it needs on every call, so your .taskrc doesn't need changes.
Connect a client
OpenCode
~/.config/opencode/opencode.json:
{
"mcp": {
"servers": {
"taskwarrior": {
"type": "local",
"command": ["taskwarrior-mcp"],
"cwd": "/home/you",
"pool": true,
"codemode": false
}
}
}
}pool: true runs one server process for all sessions; give it a fixed cwd (your home folder). codemode: false keeps the tools visible instead of behind a search step. Then install the plugin, which tells the server each session's folder and injects the context block:
cp integrations/opencode/taskwarrior-context.js ~/.config/opencode/plugins/Claude Code
claude mcp add taskwarrior -- taskwarrior-mcpClaude Code tells the server the project folder (CLAUDE_PROJECT_DIR), and calls that don't name a folder use it. Add "Call task_context at the start of a session" to your CLAUDE.md.
Other clients
{ "mcpServers": { "taskwarrior": { "command": "taskwarrior-mcp" } } }Calls without a folder use the folder the client started the server in. If the client runs one server for several projects, the agent has to pass cwd (the working folder) in each call.
How the project is chosen
The server expects work to live in <root>/<Job>/<repo>/…:
~/projects/ a root
AcmeProjects/ job "acme" (lowercased, a trailing "Projects" is dropped)
api/ project "acme.api"
web/ project "acme.web"
Operators/Operator_1/ lane "AcmeProjects/Operator_1" in job "acme"Roots default to projects, Projects, Work, work, code and src under any home folder. Set TASKWARRIOR_MCP_ROOTS to change them.
Each task records the folder it was created in (repo_path). Once a folder has at least 3 tasks and 60% of them are in one project, that project wins over the folder name. Renamed or oddly named folders still land in the right project.
The root of a job (~/projects/AcmeProjects) shows the whole job. A folder outside every root gives no scope, and the tools ask for job/repo.
Tools
Tool | What it does |
| Start here: your claims, handoffs for you, tasks other lanes hold, NEXT, blocked, waiting on owner. |
| Filter by status, plain-text search (description, context, notes), tags, priority, kind, stale, claimed, waiting on owner. |
| One task in full: claim, handoff, context, dependencies, last 5 notes. |
| New task in the folder's project. Returns the existing open task instead of a duplicate. |
| Fields, a note, or a status ( |
|
|
Fields agents can set: priority (H/M/L), kind (bug, feature, research, followup, decision, admin, test, release), tags, due, scheduled, wait, depends (short ids; on update it replaces the list), context_summary, waiting_on (who must act; keeps the task out of NEXT), gate (0–8) and risk (A–E) for teams that track review gates.
Tasks with no activity for 60 days stay open but leave NEXT. task_list stale: true shows them.
Several agents at once
Claims are per session. With OpenCode the session id comes from the request; other clients get one identity per server process.
Lanes: a session in
AcmeProjects/Operators/Operator_2acts asAcmeProjects/Operator_2, so a replacement session in the same folder continues that lane's claims. Run one session per lane folder.A handoff target must be an existing lane folder. The giver keeps the claim (extended to 4 hours) until the receiver accepts. If the giver's claim lapses and a third lane takes the task, the accept is refused.
Writes to a task another lane has claimed are refused, notes included. Coordinate with that lane or hand off.
One ledger, several machines
Run the ledger on one machine. On the others, point the MCP client at the ssh relay, which reconnects after network drops and sleep:
"command": ["node", "/path/to/Taskwarrior-MCP/integrations/ssh-relay.mjs"],
"environment": { "TASKWARRIOR_MCP_SSH": "ledger-host" }For the OpenCode plugin on those machines, set TASKWARRIOR_MCP_SSH=ledger-host in OpenCode's environment. The relay needs key-based ssh and taskwarrior-mcp installed on the ledger host. Paths from different machines match as long as the folders below the root have the same names.
Configuration
Variable | Default | |
|
| Colon-separated roots; |
|
| Idle days before a task leaves NEXT |
|
| Timeout for each |
| hostname | Machine label in claim owners |
|
| Claim owner for clients that send no session id |
|
| Used by the backup and maintenance scripts |
Backups and cleanup
npm run backup # export + raw data files, then restores them into a temp ledger to prove they work
npm run maintenance -- normalize # dry run: merge projects spelled several ways
npm run maintenance -- normalize --apply # applies, after writing a backup and a manifest
npm run maintenance -- stop-stale-active --apply # stop tasks left "active" by expired claimsRun the backup on a schedule (cron or a systemd timer) into a folder your machine backup covers.
Limits
Claims are leases. They stop agents that use this server; someone running
taskby hand can still change a claimed task.The lock file serializes every server process that uses the same Taskwarrior data folder. Taskwarrior's own sync (taskd, TaskChampion sync) is untested.
How Taskwarrior stores backslashes differs between versions. The server handles 2.6 and 3.x and the tests check it. Run
npm testafter upgrading Taskwarrior.
Development
npm test # build, 33 behaviour tests, then multi-session and two-process race testsTests run against temporary ledgers and never touch your own data. See docs/reference.md for internals.
License
MIT
Available Tools
6 toolstask_claimA
Mutation-scope claims (operator methodology). Claim once when you start a scope and release once when you stop; task_update keeps the claim alive in between. claim: take a lease (default 30 min; pass minutes for long work). release: give it up. handoff: keep it until to accepts (needs note with state + next action). accept: take a handoff addressed to your lane. takeover: take a claim from a session confirmed gone (needs note with reason).
Inputs: id (required), action (required), to, cwd, +2 more.
task_contextA
Start here. Working view for this folder's project: your claims, handoffs for you, tasks other operators hold, NEXT ready work, blocked, waiting on owner. Scope comes from the session folder; pass all_projects for a per-project overview.
Inputs: cwd, job, repo, limit, +2 more.
task_createA
Create a durable task for work that outlives this session (multi-session work, blockers, follow-ups, handoffs). Not for work you finish now. Project comes from the session folder unless job/repo is given. Returns an existing open task instead of a duplicate. claim:true claims it immediately.
Inputs: description (required), cwd, due, job, +17 more.
task_getA
Full detail of one task: claim, handoff, context, dependencies, last 5 notes.
Inputs: id (required), cwd.
task_listB
Search/filter tasks in scope. Defaults to open tasks in this folder's project, most urgent first. stale:true shows tasks untouched for 60+ days.
Inputs: cwd, job, kind, repo, +11 more.
task_updateA
Change a task: fields, a progress note, or status (done / deleted with reason / pending to reopen). Claims it for you first and renews your claim (never shortens it), so no task_claim is needed before or after an update; refuses if another operator holds it. Set waiting_on:"" to clear.
Inputs: id (required), cwd, due, gate, +15 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool targets a distinct aspect of task management: claim lifecycle, context dashboard, search/list, single-task detail, creation, and updates. The only mild overlap is between task_context (curated view) and task_list (search/filter), but descriptions clarify their different roles.
All tools use a consistent `task_` prefix and snake_case, with most following a verb_noun pattern (claim, list, get, create, update). `task_context` is a noun and slightly breaks the verb pattern, but the set remains highly predictable.
Six tools are well-scoped for a task management server with claim/handoff workflows. Each tool has a clear, non-redundant purpose, and the count is neither thin nor bloated.
The surface covers full task lifecycle (create, read, update, delete via status change) plus a sophisticated claim/handoff mechanism. Minor gaps exist, such as no explicit tool for adding/removing dependencies or managing tags, though task_update may accommodate some field changes.
Maintenance
Related MCP Connectors
Shared task layer for AI agents: tasks, handoffs and decisions that persist across tools.
One shared project for a team's coding agents: decisions, a task board and handoffs.
Task tracking built for coding agents. Work is leased, so two agents never take the same SubTask.
Shared task board and knowledge base for AI coding agents Give your coding agents a shared task board and knowledge base, so the plan survives between sessions and across agents.
Related MCP Servers
- FlicenseAqualityBmaintenanceEnables coding agents to track and coordinate project work through a shared SQLite ledger, including task plans, session ancestry, claims, work locations, blockers, and commits via MCP tools.9-
- AlicenseAqualityCmaintenanceEnables a planning Claude chat and Claude Code to exchange work through local Markdown files, letting the chat create tasks that code agents pick up, complete, and report back on. Project-scoped task and report tools track each item's status from open through reported, eliminating manual copy-paste between the two clients.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables coding agents to read a task's live brief and update progress, checkpoint, hand off, create, and list tasks from within their own editor. A newly connected chat receives the current task state automatically, so work continues without re-explaining context.5Apache 2.0
- AlicenseNot gradedqualityAmaintenanceEnables structured multi-agent workflows by managing task claims, action logs, handoffs, and health-gated completion while keeping specifications as filesystem Markdown artifacts.29 npmMIT