Obsidian Tasks MCP Server
About
A Model Context Protocol (MCP) server that extracts and queries tasks from Obsidian markdown files using the Obsidian Tasks plugin format. Designed to enable AI-assisted task management with Claude via the MCP protocol.
Details
- Author
- jfim
- GitHub stars
- 15
- Downloads
- 443
- Categories
- Knowledge Base, Project Management
Jump to
- Extracts tasks from Obsidian markdown files recursively through subfolders.
- Provides two tools: list_all_tasks and query_tasks.
- Supports metadata: status, due/scheduled/start/created dates, tags, priority, recurrence.
- Fully compatible with Obsidian Tasks emoji and Dataview task formats.
- Includes a query_tasks tool with rich filter syntax (status, dates, tags, path, description, priority).
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Obsidian Tasks MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
Install globally via npm (npm install -g @jfim/obsidian-tasks-mcp) or run directly with npx. Specify the path to your Obsidian vault as a command-line argument when starting the server. Add the server configuration to your MCP-supporting client (e.g., Claude Desktop) using the JSON configuration shown in the README.
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"obsidian tasks mcp server": {
"obsidian-tasks-mcp": {
"command": "npx",
"args": [
"@jfim/obsidian-tasks-mcp",
"/path/to/obsidian/vault"
]
}
}
}
}McpServers
{
"obsidian-tasks-mcp": {
"command": "npx",
"args": [
"@jfim/obsidian-tasks-mcp",
"/path/to/obsidian/vault"
]
}
}Obsidian Tasks MCP Server
A Model Context Protocol (MCP) server for extracting and querying Obsidian Tasks from markdown files. Designed to work with Claude via the MCP protocol to enable AI-assisted task management.
Features
- Extract tasks from Obsidian markdown files with a format compatible with the Obsidian Tasks plugin
- Identify completed and pending tasks
- Access task metadata including:
- Status (complete/incomplete)
- Due dates
- Scheduled dates
- Start dates
- Created dates
- Tags
- Priority
- Recurrence rules
Tools
This MCP server provides the following tools:
list_all_tasks
Extracts all tasks from markdown files in a directory, recursively scanning through subfolders.
Input Parameters:
- path (string, optional): The directory to scan for markdown files. If not specified, defaults to the first allowed directory.
Returns:
A JSON array of task objects, each containing:
{
"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
Searches for tasks based on Obsidian Tasks query syntax. Applies multiple filters to find matching tasks.
Input Parameters:
- path (string, optional): The directory to scan for markdown files. If not specified, defaults to the first allowed directory.
- query (string, required): The query string using Obsidian Tasks query syntax. Each line is treated as a filter.
Returns:
A JSON array of task objects that match the query, with the same structure as list_all_tasks.
Supported Query Syntax:
- Status filters:
- done - Show completed tasks
- not done - Show incomplete tasks
- Date filters (due):
- Note on semantics: due today is an exact match (only tasks due exactly today). Use range operators to include earlier/later dates.
- due today - Tasks due today
- due before today - Tasks due before today (exclusive)
- due after today - Tasks due after today (exclusive)
- due on or before today - Tasks due today or earlier (inclusive)
- due on or after today - Tasks due today or later (inclusive)
- due on YYYY-MM-DD or due YYYY-MM-DD - Tasks due on a specific date
- due before YYYY-MM-DD - Tasks due before a date (exclusive)
- due after YYYY-MM-DD - Tasks due after a date (exclusive)
- due on or before YYYY-MM-DD - Tasks due on/before a date (inclusive)
- due on or after YYYY-MM-DD - Tasks due on/after a date (inclusive)
- no due date - Tasks with no due date
- has due date - Tasks with a due date
- Start date filters:
- Note on semantics: starts today is an exact match (only tasks that start today). Use range operators to include earlier/later dates.
- starts today - Tasks starting today
- starts on YYYY-MM-DD or starts YYYY-MM-DD - Start on a specific date
- starts before YYYY-MM-DD - Start before a date (exclusive)
- starts after YYYY-MM-DD - Start after a date (exclusive)
- starts on or before YYYY-MM-DD - Start on/before a date (inclusive)
- starts on or after YYYY-MM-DD - Start on/after a date (inclusive)
- no start date - Tasks with no start date
- has start date - Tasks with a start date
- Tag filters:
- no tags - Tasks with no tags
- has tags - Tasks with at least one tag
- tag includes #tag - Tasks with tags containing "tag"
- tag does not include #tag - Tasks without tags containing "tag"
- Path filters:
- path includes string - Tasks in files with paths containing "string"
- path does not include string - Tasks in files with paths not containing "string"
- Description filters:
- description includes string - Tasks with descriptions containing "string"
- description does not include string - Tasks with descriptions not containing "string"
- Priority filters:
- priority is highest - Tasks with highest priority
- priority is high - Tasks with high priority
- priority is medium - Tasks with medium priority
- priority is low - Tasks with low priority
- priority is lowest - Tasks with lowest priority
- priority is none - Tasks with no priority
Example Query:
not done
due before 2025-05-01
tag include #work
This would return all incomplete tasks due before May 1, 2025, that have the #work tag.
Inclusive OR example (single line):
due on or before today OR starts on or before today
Usage
Installation
From npm (recommended):
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
