Obsidian Tasks MCP Server

这是一个用于从 Markdown 文件中提取和查询 Obsidian Tasks 的 Model Context Protocol (MCP) 服务器。设计用于通过 MCP 协议与 Claude 集成，以实现 AI 辅助的任务管理。

功能

• 从 Obsidian Markdown 文件中提取任务，格式兼容 Obsidian Tasks 插件
• 标识已完成和待完成的任务
• 访问任务元数据，包括：
  • 状态（完成/未完成）
  • 截止日期
  • 安排日期
  • 开始日期
  • 创建日期
  • 标签
  • 优先级
  • 周期规则

工具

此 MCP 服务器提供以下工具：

list_all_tasks

从目录中的 Markdown 文件中提取所有任务，递归扫描子文件夹。

输入参数：

• path (字符串，可选)：要扫描的 Markdown 文件所在的目录。如果未指定，默认为第一个允许的目录。

返回值： 一个 JSON 数组，包含任务对象，每个对象包含：

{
  "id": "string",          // 唯一标识符（文件路径:行号）
  "description": "string", // 任务的全文描述
  "status": "complete" | "incomplete", // 任务完成状态
  "filePath": "string",    // 包含任务的文件路径
  "lineNumber": "number",  // 文件中的行号
  "tags": ["string"],      // 在任务中找到的标签数组
  "dueDate": "string",     // 可选 - YYYY-MM-DD 格式
  "scheduledDate": "string", // 可选 - YYYY-MM-DD 格式
  "startDate": "string",   // 可选 - YYYY-MM-DD 格式
  "createdDate": "string", // 可选 - YYYY-MM-DD 格式
  "priority": "string",    // 可选 - "高", "中", 或 "低"
  "recurrence": "string"   // 可选 - 周期规则
}

query_tasks

根据 Obsidian Tasks 查询语法搜索任务。应用多个过滤器以查找匹配的任务。

输入参数：

• path (字符串，可选)：要扫描的 Markdown 文件所在的目录。如果未指定，默认为第一个允许的目录。
• query (字符串，必需)：使用 Obsidian Tasks 查询语法的查询字符串。每行被视为一个过滤器。

返回值： 一个 JSON 数组，包含与查询匹配的任务对象，结构与 list_all_tasks 相同。

支持的查询语法：

• 状态过滤器：

  • done - 显示已完成的任务
  • not done - 显示未完成的任务

• 日期过滤器：

  • due today - 今天到期的任务
  • due before today - 在今天之前到期的任务
  • due after today - 在今天之后到期的任务
  • no due date - 没有截止日期的任务
  • has due date - 有截止日期的任务

• 标签过滤器：

  • no tags - 没有标签的任务
  • has tags - 至少有一个标签的任务
  • tag include #tag - 包含 "tag" 标签的任务
  • tag do not include #tag - 不包含 "tag" 标签的任务

• 路径过滤器：

  • path includes string - 文件路径包含 "string" 的任务
  • path does not include string - 文件路径不包含 "string" 的任务

• 描述过滤器：

  • description includes string - 描述包含 "string" 的任务
  • description does not include string - 描述不包含 "string" 的任务

• 优先级过滤器：

  • priority is high - 高优先级的任务
  • priority is medium - 中优先级的任务
  • priority is low - 低优先级的任务
  • priority is none - 没有优先级的任务

示例查询：

not done
due before 2025-05-01
tag include #work

这将返回所有未完成且在 2025 年 5 月 1 日之前到期并带有 #work 标签的任务。

使用方法

安装

从 npm 安装（推荐）：

# 全局安装
npm install -g @jfim/obsidian-tasks-mcp

# 或者无需安装直接使用 npx
npx @jfim/obsidian-tasks-mcp /path/to/obsidian/vault

从源码安装：

git clone https://github.com/jfim/obsidian-tasks-mcp.git
cd obsidian-tasks-mcp
npm install
npm run build

运行服务器

使用 npm 包（推荐）：

# 如果全局安装
obsidian-tasks-mcp /path/to/obsidian/vault

# 或者使用 npx（无需安装）
npx @jfim/obsidian-tasks-mcp /path/to/obsidian/vault

从源码运行：

node dist/index.js /path/to/obsidian/vault

您可以指定多个目录：

npx @jfim/obsidian-tasks-mcp /path/to/obsidian/vault /another/directory

测试

运行测试套件：

npm test

查看 TESTING.md 获取关于测试套件的详细信息。

与 Claude 集成

在支持 MCP 的 Claude 客户端中添加以下配置：

{
  "mcpServers": {
    "obsidian-tasks": {
      "command": "npx",
      "args": [
        "@jfim/obsidian-tasks-mcp",
        "/path/to/obsidian/vault"
      ]
    }
  }
}

如果从源码安装：

{
  "mcpServers": {
    "obsidian-tasks": {
      "command": "node",
      "args": [
        "/path/to/obsidian-tasks-mcp/dist/index.js",
        "/path/to/obsidian/vault"
      ]
    }
  }
}

Docker

构建 Docker 镜像：

docker build -t @jfim/obsidian-tasks-mcp .

使用 Docker 运行：

docker run -i --rm --mount type=bind,src=/path/to/obsidian/vault,dst=/projects/vault @jfim/obsidian-tasks-mcp /projects

Claude Desktop 配置：

{
  "mcpServers": {
    "obsidian-tasks": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--mount", "type=bind,src=/path/to/obsidian/vault,dst=/projects/vault",
        "@jfim/obsidian-tasks-mcp",
        "/projects"
      ]
    }
  }
}

任务格式

服务器识别以下 Obsidian Tasks 格式：

• 任务语法：- [ ] 任务描述
• 完成任务：- [x] 任务描述
• 截止日期：
  • 🗓️ YYYY-MM-DD
  • 📅 YYYY-MM-DD
• 安排日期：⏳ YYYY-MM-DD
• 开始日期：🛫 YYYY-MM-DD
• 创建日期：➕ YYYY-MM-DD
• 优先级：⏫（高），🔼（中），🔽（低）
• 周期：🔁 每天/每周/每月等。
• 标签：#标签1 #标签2

示例任务：- [ ] 完成项目报告 🗓️ 2025-05-01 ⏳ 2025-04-25 #工作 #报告 ⏫

许可证

MIT 许可证