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"
      }
    }
  }
}

On Windows, use cmd /c in front of npx. Desktop MCP clients like Claude Desktop start the server without a shell, and npx is a .cmd script Windows will only run through one:

{
  "mcpServers": {
    "taskforge": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "taskforge-md", "mcp", "--stdio"],
      "env": {
        "TASKFORGE_VAULT": "C:\\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 and Windows, and the MCP server is one of its subcommands. Linux is coming soon.

The full tool set

30 tools in total, covering the whole task and note lifecycle: create, read, update, complete, archive, and delete, each with a bulk variant; move, reparent, and convert between an inline line and a task file; create, rename, delete, and edit notes without breaking a link; a lint check before you write a line; a doctor call for vault health; and dialect and spaces 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_spaces, get_dialect, create_note, read_note, update_note, patch_note_block, patch_note_frontmatter, normalize_references, delete_note, and move_note.

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

The TaskForge MCP server runs locally and reads and writes your vault's Markdown files. Installing through npx downloads the package from npm. Your AI client may send tool inputs and results to its provider; its privacy settings still apply. Your existing vault sync carries edits 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