让智能体来打理你的待办清单

MCP 还是 CLI？

如果你的智能体已经与 TaskForge 建立了 MCP 连接，优先使用 MCP 工具。它们是类型化的，返回结构化错误，方便智能体据此自我纠正，而且不需要在你的 PATH 里安装任何东西。如果是没有 MCP 连接的 shell 环境，比如脚本、cron、CI，或是在代码仓库检出目录里工作的编程智能体，改用 CLI。两者驱动的是同一个引擎，语义完全一致，选择你运行环境里已经接好的那一个就行。手动编辑仓库文件是最后的办法。

安装

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

在 Windows 上，请在 npx 前加上 cmd /c。像 Claude Desktop 这样的桌面 MCP 客户端启动服务器时不经过 shell，而 npx 是 .cmd 脚本，Windows 只能通过 shell 运行它：

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

自己从源码编译了 taskforge，而不是用 npx？把配置直接指向该二进制文件：

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

仅支持桌面端，因为 MCP 客户端都运行在桌面环境中。taskforge 以单一原生二进制文件的形式发布，支持 macOS 和 Windows，MCP 服务器是它的子命令之一。Linux 版即将推出。

完整工具集

共有 30 个工具，覆盖任务和笔记的完整生命周期：创建、读取、更新、完成、归档和删除，每个都有对应的批量版本；移动、更改上级任务，以及在内联行与任务文件之间转换；创建、重命名、删除和编辑笔记，且不会弄断链接；写入前的 lint 校验；检查仓库健康状况的 doctor 调用；以及任务语法和空间资源，让智能体在操作前先了解你的格式。下面这六个是最常用的。每次调用都会从磁盘重新读取仓库，因此智能体操作的始终是最新的文件。

每个工具都带有注解，客户端可以一眼看出哪些调用只读、哪些会写入、哪个会删除。其余工具还包括 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 和 move_note。

三个资源

除了工具之外，服务器还暴露了一些只读上下文信息，让智能体在操作之前先了解你仓库的规则：

如果找不到你的仓库

服务器总会正常启动，哪怕它还不知道你的仓库在哪里，因此 Claude Desktop 不会显示一条含糊的“服务器启动失败”提示。当某次工具调用无法确定仓库位置时，它会返回一条清晰的错误信息供智能体转达：将 TASKFORGE_VAULT 环境变量设为你的仓库路径，或者重新安装安装包，并在提示时输入仓库目录。

仅在本地运行

TaskForge MCP 服务器在本地运行，读写你仓库中的 Markdown 文件。通过 npx 安装时会从 npm 下载软件包。你的 AI 客户端可能会把工具的输入和结果发送给它的提供方，它自己的隐私设置依然适用。你现有的仓库同步会在设备之间传递这些改动。

更喜欢终端？

如果你想通过脚本操作任务，或者运行一次性命令，而不是交给智能体来驱动，taskforge CLI 面向的是同一个仓库、同一套规则。

常见问题