Let an agent run your to-do list

MCP or the CLI?

Prefer the MCP tools when your agent already has an MCP connection to TaskForge. They are typed, return structured errors the agent can self-correct against, and need nothing on your PATH. Reach for the CLI instead from shell contexts with no MCP connection: scripts, cron, CI, or a coding agent working in a repo checkout. Both drive the same engine with identical semantics, so pick whichever your runtime already has wired up. Editing vault files by hand is the last resort.

Install

{
  "mcpServers": {
    "taskforge": {
      "command": "npx",
      "args": ["-y", "taskforge-md", "mcp", "--stdio"],
      "env": {
        "TASKFORGE_VAULT": "/path/to/your/vault"
      }
    }
  }
}

Built taskforge from source instead of using npx? Point the config at the binary directly:

"command": "taskforge",
"args": ["mcp", "--stdio"]

Desktop only, since that is where MCP clients live. taskforge ships as a single native binary for macOS, Windows, and Linux, and the MCP server is one of its subcommands.

The full tool set

22 tools in total, covering the whole task lifecycle: create, read, update, complete, archive, and delete, each with a bulk variant; move, reparent, and convert between an inline line and a TaskNotes file; a lint check before you write a line; a doctor call for vault health; and schema and list resources so the agent learns your format before it acts. The six below are the ones you will reach for most. Every call re-reads the vault from disk, so the agent always acts on the current files.

Each tool carries annotations, so a client knows at a glance which calls only read, which write, and which one deletes. The rest of the set adds bulk_add_tasks, bulk_update_tasks, bulk_complete_tasks, bulk_delete_tasks, get_tasks, archive_task, move_task, bulk_move_tasks, convert_task, bulk_convert_tasks, outdent_task, bulk_reparent_tasks, lint_task, doctor, list_task_lists, and get_schema.

Three resources

Alongside the tools, the server exposes read-only context so the agent learns your vault's rules before it acts:

If it cannot find your vault

The server always starts, even before it knows where your vault is, so Claude Desktop never shows an opaque "server failed to start". When a tool call cannot resolve a vault, it returns a plain error the agent can relay: set the TASKFORGE_VAULT environment variable to your vault path, or reinstall the bundle and enter the vault directory when prompted.

Local only

taskforge mcp --stdio reads and writes the markdown files in the vault you configure and nothing else. No account, no cloud. Your existing sync, iCloud, Dropbox, or Obsidian Sync, moves the changes between devices.

Prefer a terminal?

If you want to script your tasks or run one-off commands rather than drive them from an agent, the taskforge CLI covers the same vault with the same rules.

Questions people ask