优化黑曜石任务MCP
](https://badge.fury.io/js/optimike-obsidian-tasks-mcp)
用于从markdown文件中提取和查询黑曜石任务的模型上下文协议（MCP）服务器。旨在与MCP客户（Claude、Codex、IDE等）合作，实现人工智能辅助的任务管理。
法文版本： README.fr.md
先决条件
- Node.js>=16
- 黑曜石桌面
- 在vault中配置的黑曜石任务插件：https://github.com/obsidian-tasks-group/obsidian-tasks
- 任务配置文件位于：
/.obsidian/plugins/obsidian-tasks/data.json
快速入门
npx optimike-obsidian-tasks-mcp /path/to/obsidian/vault特性
- 从兼容黑曜石任务设置的黑曜岩标记文件中提取任务
- 由Tasks插件配置驱动的状态映射（核心+自定义状态）
- 支持任务全局过滤器+预设（可选）
- 具有相对范围（EN/FR）和比较的日期过滤器
- 可选数据视图任务格式解析(
[due:: 2024-01-01]等等） - 可选的文件元数据+frontmatter元数据日期（可回退到文件系统）
- 输出为JSON或Markdown
任务插件配置（事实来源）
此服务器依赖于Obsidian Tasks插件： https://github.com/obsidian-tasks-group/obsidian-tasks
此服务器从以下位置读取您的任务插件设置（状态、预设、全局过滤器）：
/.obsidian/plugins/obsidian-tasks/data.json确保该文件反映了您当前的任务配置。
工具
此MCP服务器提供以下工具：
list_all_任务
从目录中的markdown文件中提取所有任务，递归扫描子文件夹。
输入参数：
path（字符串，可选）：要扫描的目录。默认为vault根目录。includePaths（string\[\]，可选）：仅包含包含这些子字符串的路径。excludePaths（string\[\]，可选）：排除包含这些子字符串的路径。includeNonTasks（布尔值，可选）：包括NON_TASK状态。includeFileMetadata（布尔值，可选）：包括文件创建/修改日期。includeMetaDates（布尔值，可选）：包括前台元数据日期（例如，变更/修改）。metaFallbackToFile（布尔值，可选，默认为true）：如果缺少元数据日期，则回退到文件日期。applyGlobalFilter（布尔值，可选）：应用任务globalFilter.responseFormat（“json”|“markdown”，可选）：输出格式。responseLimit（number，可选）：限制返回的任务数。useCache（boolean，可选，默认为true）：缓存每个文件解析。
退货： 任务对象的JSON数组，每个对象包含：
{
"id": "string", // Unique identifier (filepath:linenumber)
"description": "string", // Full text description of the task
"status": "complete" | "incomplete" | "cancelled" | "in_progress" | "non_task",
"statusName": "string", // Optional - status name from Tasks config
"statusType": "string", // Optional - TODO | DONE | IN_PROGRESS | CANCELLED | NON_TASK
"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
"doneDate": "string", // Optional - YYYY-MM-DD format
"cancelledDate": "string", // Optional - YYYY-MM-DD format
"metaCreatedDate": "string", // Optional - from frontmatter
"metaModifiedDate": "string", // Optional - from frontmatter
"fileCreatedDate": "string", // Optional - filesystem
"fileModifiedDate": "string", // Optional - filesystem
"priority": "string", // Optional - "high", "medium", or "low"
"recurrence": "string" // Optional - recurrence rule
}查询任务
根据黑曜石任务查询语法搜索任务。应用多个筛选器来查找匹配的任务。
输入参数：
path（字符串，可选）：要扫描的目录。默认为vault根目录。query（字符串，必填）：任务查询。每条线都被视为一个过滤器。queryFilePath（字符串，可选）：用于解析{{query.file.*}}占位符。- 所有其他参数来自
list_all_tasks（包括/排除、元数据日期、全局过滤器等）
退货： 与查询匹配的任务对象的JSON数组，其结构与 list_all_tasks.
支持的查询语法（子集+附加项）：
- 状态筛选器：
- done / not done （与任务语义一致） - status.type is TODO|DONE|IN_PROGRESS|CANCELLED|NON_TASK - status.name is "In Progress"
- 日期筛选器：
- due|scheduled|start|created on|before|after YYYY-MM-DD - due|scheduled|start|created on or before|on or after - 相对EN/FR： today, tomorrow, yesterday, this week, next week, last week, aujourd'hui, demain, hier, cette semaine, semaine prochaine - 范围： due in next 7 days - 元/文件： meta created before 2026-01-01, file modified after 2025-12-31
- 标签过滤器：
- no tags, has tags - tag include #tag / tag do not include #tag
- 路径筛选器：
- path includes string, path does not include string - folder includes string, filename includes string
- 描述过滤器：
- description includes string -描述包含“字符串”的任务 - description does not include 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（推荐）：
# Install globally
npm install -g optimike-obsidian-tasks-mcp
# Or use directly with npx without installing
npx optimike-obsidian-tasks-mcp /path/to/obsidian/vault来源：
git clone https://github.com/optimikelabs/optimike-obsidian-tasks-mcp.git
cd optimike-obsidian-tasks-mcp
npm install
npm run build运行服务器
使用npm包（推荐）：
# If installed globally
optimike-obsidian-tasks-mcp /path/to/obsidian/vault
# Or with npx (no installation required)
npx optimike-obsidian-tasks-mcp /path/to/obsidian/vault来源：
node dist/index.js /path/to/obsidian/vault您可以指定多个目录：
npx optimike-obsidian-tasks-mcp /path/to/obsidian/vault /another/directoryHTTP传输（可选）
服务器还支持流式HTTP传输。
MCP_TRANSPORT_TYPE=http MCP_HTTP_HOST=127.0.0.1 MCP_HTTP_PORT=3011 \
npx optimike-obsidian-tasks-mcp /path/to/obsidian/vault会话模式（默认 stateful):
MCP_HTTP_SESSION_MODE=stateful（自动会话ID）MCP_HTTP_SESSION_MODE=stateless（无会话）
性能和范围
为避免扫描过多，请使用 includePaths/excludePaths 在MCP呼叫中， 或通过env-vars设置默认值：
MCP_TASKS_INCLUDE_PATHS（CSV）：vault相对路径，例如。Efforts/Projets,Calendrier/NOTES PÉRIODIQUESMCP_TASKS_EXCLUDE_PATHS（CSV）MCP_TASKS_MAX_FILES（编号）MCP_TASKS_CONCURRENCY（数字，默认为8）
测试
要运行测试套件，请执行以下操作：
npm test看 测试.md 有关测试套件的详细信息。
检验（MCP检验员）
npm run inspect:stdio
# or
npm run inspect:http与MCP客户端（Claude、Codex等）一起使用
将此配置添加到支持MCP的客户端：
{
"mcpServers": {
"optimike-obsidian-tasks": {
"command": "npx",
"args": [
"optimike-obsidian-tasks-mcp",
"/path/to/obsidian/vault"
]
}
}
}如果从源代码安装：
{
"mcpServers": {
"optimike-obsidian-tasks": {
"command": "node",
"args": [
"/path/to/optimike-obsidian-tasks-mcp/dist/index.js",
"/path/to/obsidian/vault"
]
}
}
}码头工人
构建Docker镜像：
docker build -t optimike-obsidian-tasks-mcp .使用Docker运行：
docker run -i --rm --mount type=bind,src=/path/to/obsidian/vault,dst=/projects/vault optimike-obsidian-tasks-mcp /projectsClaude桌面配置：
{
"mcpServers": {
"optimike-obsidian-tasks": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"--mount", "type=bind,src=/path/to/obsidian/vault,dst=/projects/vault",
"optimike-obsidian-tasks-mcp",
"/projects"
]
}
}
}任务格式
服务器识别以下黑曜石任务格式：
- 任务语法：
- [ ] 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许可证