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

在找一个操作真实文件、而不是托管数据库的待办 MCP 服务器？taskforge 以子命令 taskforge mcp --stdio 的形式，为您的 Obsidian 仓库提供了这样一个服务器。把 Claude Desktop 或其他 MCP 客户端指向它，智能体就能通过一小组工具添加、搜索、编辑和完成任务。它运行在您自己的电脑上，编辑的是应用所使用的同一批 markdown 文件。没有托管服务器，也不需要 API 密钥。

即将随 TaskForge 3.0 推出

TaskForge 命令行工具和 MCP 服务器将随 TaskForge 3.0 版本一起发布。本页内容描述的是它们上线后的使用方式。TaskForge 应用本身现在就可以下载使用。

MCP 还是 CLI？

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

安装

Claude Desktop：一键安装

更喜欢向导式安装？下载 taskforge 安装包（.mcpb 文件）并打开它。Claude Desktop 会引导您完成设置，并询问您的仓库文件夹位置。

上线后即可使用

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

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

上线后即可使用

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

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

完整工具集

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

query_tasks	搜索和筛选任务，或读取一个已保存的列表。只读。	只读
get_task	读取一个任务及其内容哈希。只读。	只读
add_task	在仓库的默认目标位置，按您的格式创建一个任务。	写入
update_task	修改任务的状态、优先级、截止日期、标题或标签。	写入
complete_task	完成一个任务，如果它会循环，返回下一次发生的任务。	写入，非幂等
delete_task	删除一个任务。模型必须原样回传当前的准确标题，以防止对过期或臆造的 id 执行操作。	破坏性操作

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

三个资源

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

taskforge://schema	机器可读的任务方言：状态符号、日期格式、自定义字段、写入目标。
taskforge://agents-guide	用大白话说明您仓库任务约定的指南。
taskforge://lists	您保存的任务列表，以及如何向每个列表添加任务。

唯一的前提条件：仓库契约文件

服务器会读取 TaskForge 写入您仓库的契约文件 taskforge/schema.json 和 taskforge/agents.md，从中了解您精确的任务格式。请至少用 TaskForge 3.0 或更高版本打开一次仓库，进入 Settings, AI & Agents，并保持 'Generate agent files' 开关为开启状态。如果该仓库从未在较新版本的应用中打开过，服务器会退回到通用默认值，并向客户端发出警告。

如果找不到您的仓库

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

仅在本地运行

taskforge mcp --stdio 只读写您配置的仓库中的 markdown 文件，不涉及其他任何内容。不需要账号，不依赖云端。您原有的同步方式，无论是 iCloud、Dropbox 还是 Obsidian Sync，都会把改动带到您的其他设备。

更喜欢终端？

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

安装 taskforge CLI →

常见问题

什么是 taskforge MCP 服务器？

它是内置在 taskforge 二进制文件中的本地 Model Context Protocol 服务器。用 taskforge mcp --stdio 运行它，Claude Desktop 这样的 MCP 客户端就能通过 22 个类型化的工具（单个或批量），添加、查找、编辑、移动、完成和删除您 Obsidian 仓库里的任务。它不只是能读，而是一份智能体可以真正操作的待办清单。

它能配合哪些 MCP 客户端使用？

任何通过 stdio 支持 MCP 的客户端都可以。Claude Desktop 最常见，Claude Code、Cursor 以及 VS Code（用于 GitHub Copilot）也都使用相同的配置。每一个都能获得同样的 22 个工具和三个资源。

这是托管或远程的 MCP 服务器吗？

不是。它运行在您自己的电脑上，通过 stdin 和 stdout 通信，只会接触您指定的仓库文件夹。没有需要托管的 URL，没有 API 密钥，也没有 TaskForge 账号。这正是关键所在：您的待办清单留在您自己的硬盘上。

我需要提前安装什么吗？

不需要提前安装。把客户端配置指向 npx -y taskforge-md mcp --stdio，npx 会在首次运行时获取这个包。Claude Desktop 用户也可以直接打开 .mcpb 安装包，走向导式安装。

客户端提示服务器找不到我的仓库，该怎么办？

服务器总会正常启动，所以客户端不会显示一条含糊的 '启动失败' 提示。当某次工具调用无法确定仓库位置时，它会返回一条清晰的消息：将 TASKFORGE_VAULT 环境变量设为您的仓库路径，或者重新安装安装包，并在提示时输入仓库目录。

它需要仓库契约文件吗？

需要，这样才能匹配您的格式。它会读取 taskforge/schema.json 和 taskforge/agents.md，这两个文件在您用 TaskForge 3.0 或更高版本打开仓库并开启 'Generate agent files' 时生成。没有它们服务器依然能运行，但会退回到通用默认值，并向客户端警告它在猜测。