Skip to main content
Glama

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.

CI

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/api works in project acme.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_N folders 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 PATH

The 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-mcp

Claude 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

task_context

Start here: your claims, handoffs for you, tasks other lanes hold, NEXT, blocked, waiting on owner. all_projects: true gives counts per project.

task_list

Filter by status, plain-text search (description, context, notes), tags, priority, kind, stale, claimed, waiting on owner.

task_get

One task in full: claim, handoff, context, dependencies, last 5 notes.

task_create

New task in the folder's project. Returns the existing open task instead of a duplicate. claim: true claims it.

task_update

Fields, a note, or a status (done, deleted with a reason, pending with a reason to reopen). Claims the task for you and renews your claim; a rejected change leaves no claim behind.

task_claim

claim, release, handoff (to a lane, with a note), accept, takeover (with a reason).

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_2 acts as AcmeProjects/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

TASKWARRIOR_MCP_ROOTS

/home/*/projects:/home/*/Work:…

Colon-separated roots; * matches one folder

TASKWARRIOR_MCP_STALE_DAYS

60

Idle days before a task leaves NEXT

TASKWARRIOR_MCP_TASK_TIMEOUT_MS

30000

Timeout for each task call

TASKWARRIOR_MCP_HOST

hostname

Machine label in claim owners

TASKWARRIOR_MCP_AGENT_ID

mcp-<host>-<pid>

Claim owner for clients that send no session id

TASKWARRIOR_BACKUP_DIR

~/.task-backups

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 claims

Run 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 task by 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 test after upgrading Taskwarrior.

Development

npm test    # build, 33 behaviour tests, then multi-session and two-process race tests

Tests run against temporary ledgers and never touch your own data. See docs/reference.md for internals.

License

MIT

Available Tools

6 tools
task_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

    A3.8/5.0

    Scored across 6 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      A
      quality
      B
      maintenance
      Enables 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
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables 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.
      5
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      5
      Apache 2.0
    • A
      license
      Not graded
      quality
      A
      maintenance
      Enables structured multi-agent workflows by managing task claims, action logs, handoffs, and health-gated completion while keeping specifications as filesystem Markdown artifacts.
      29 npm
      MIT