Obsidian Tasks MCP Server

Obsidian Tasks MCP 服务

一个用于从 Markdown 文件中提取和查询 Obsidian Tasks 的模型上下文协议（MCP）服务。该服务旨在通过 MCP 协议与 Claude 配合使用，实现 AI 辅助任务管理。

功能

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

工具

此 MCP 服务提供以下工具：

list_all_tasks

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

输入参数：

• path（字符串，可选）：要扫描 Markdown 文件的目录。如果未指定，则默认为第一个允许访问的目录。

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

{
  "id": "string",          // Unique identifier (filepath:linenumber)
  "description": "string", // Full text description of the task
  "status": "complete" | "incomplete", // Task completion status
  "filePath": "string",    // Path to the file containing the task
  "lineNumber": "number",  // Line number in the file
  "tags": ["string"],      // Array of tags found in the task
  "dueDate": "string",     // Optional - YYYY-MM-DD format 
  "scheduledDate": "string", // Optional - YYYY-MM-DD format
  "startDate": "string",   // Optional - YYYY-MM-DD format
  "createdDate": "string", // Optional - YYYY-MM-DD format
  "priority": "string",    // Optional - "high", "medium", or "low"
  "recurrence": "string"   // Optional - recurrence rule
}

query_tasks

根据 Obsidian Tasks 查询语法搜索任务。应用多个筛选条件，查找匹配的任务。

输入参数：

• path（字符串，可选）：要扫描 Markdown 文件的目录。如果未指定，默认为第一个允许的目录。
• query（字符串，必需）：使用 Obsidian Tasks 查询语法的查询字符串。每一行都视为一个筛选条件。

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

支持的查询语法：

• 状态筛选：

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

• 日期筛选（截止日期）：

  • 语义说明：due today 是精确匹配（仅匹配截止日期恰好为今天的任务）。使用范围运算符可包含更早或更晚的日期。
  • due today - 截止日期为今天的任务
  • due before today - 截止日期早于今天的任务（不含今天）
  • due after today - 截止日期晚于今天的任务（不含今天）
  • due on or before today - 截止日期为今天或更早的任务（含今天）
  • due on or after today - 截止日期为今天或更晚的任务（含今天）
  • due on YYYY-MM-DD 或 due YYYY-MM-DD - 截止日期为指定日期的任务
  • due before YYYY-MM-DD - 截止日期早于指定日期的任务（不含该日期）
  • due after YYYY-MM-DD - 截止日期晚于指定日期的任务（不含该日期）
  • due on or before YYYY-MM-DD - 截止日期为指定日期或更早的任务（含该日期）
  • due on or after YYYY-MM-DD - 截止日期为指定日期或更晚的任务（含该日期）
  • no due date - 没有截止日期的任务
  • has due date - 有截止日期的任务

• 开始日期筛选：

  • 语义说明：starts today 是精确匹配（仅匹配开始日期为今天的任务）。使用范围运算符可包含更早或更晚的日期。
  • starts today - 今天开始的任务
  • starts on YYYY-MM-DD 或 starts YYYY-MM-DD - 在指定日期开始的任务
  • starts before YYYY-MM-DD - 在指定日期之前开始的任务（不含该日期）
  • starts after YYYY-MM-DD - 在指定日期之后开始的任务（不含该日期）
  • starts on or before YYYY-MM-DD - 在指定日期或之前开始的任务（含该日期）
  • starts on or after YYYY-MM-DD - 在指定日期或之后开始的任务（含该日期）
  • no start date - 没有开始日期的任务
  • has start date - 有开始日期的任务

• 标签筛选：

  • no tags - 没有标签的任务
  • has tags - 至少有一个标签的任务
  • tag includes #tag - 标签中包含 “tag” 的任务
  • tag does 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 highest - 优先级最高的任务
  • priority is high - 优先级高的任务
  • priority is medium - 优先级中等的任务
  • priority is low - 优先级低的任务
  • priority is lowest - 优先级最低的任务
  • priority is none - 没有优先级的任务

查询示例：

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

这将返回所有未完成、截止日期早于 2025 年 5 月 1 日且带有 #work 标签的任务。

包含式 OR 示例（单行）：

due on or before today OR starts on or before today

使用方法

安装

从 npm 安装（推荐）：

# Install globally
npm install -g @jfim/obsidian-tasks-mcp

# Or use directly with npx without installing
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 包（推荐）：

# If installed globally
obsidian-tasks-mcp /path/to/obsidian/vault

# Or with npx (no installation required)
npx @jfim/obsidian-tasks-mcp /path/to/obsidian/vault

从源代码运行：

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

测试

运行测试套件：

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/src/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 表情符号格式和 Dataview 格式的任务元数据。

• 任务语法：- [ ] Task description
• 已完成的任务：- [x] Task description
• 截止日期：
  • 🗓️ YYYY-MM-DD
  • 📅 YYYY-MM-DD
• 计划日期：⏳ YYYY-MM-DD
• 开始日期：🛫 YYYY-MM-DD
• 创建日期：➕ YYYY-MM-DD
• 优先级：⏫（高）、🔼（中）、🔽（低）
• 重复周期：🔁 every day/week/month/etc.
• 标签：#tag1 #tag2

任务示例：- [ ] Complete project report 🗓️ 2025-05-01 ⏳ 2025-04-25 #work #report ⏫

许可证

MIT 许可证