Obsidian Tasks MCP

🚀 Obsidian Tasks MCP Server

An Model Context Protocol (MCP) server designed to extract and query Obsidian tasks from Markdown files. It's intended to work with Claude, implementing functions through the MCP protocol.

🚀 Quick Start

The Obsidian Tasks MCP Server provides a set of tools to extract, query, and analyze Obsidian tasks from Markdown files. Here's how you can get started:

Installation

You can install the package using npm:

npm install -g @jfim/obsidian-tasks-mcp

Or build it from the source code:

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

Running the Server

After global installation, you can run the server with:

obsidian-tasks-mcp /path/to/vault

If you built from source, start it with:

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

✨ Features

• Task Extraction: Supports identifying and parsing task items in various formats.
• Time Information Handling: Deals with time information such as due dates and scheduled dates.
• Priority Identification: Recognizes high, medium, and low priority markers.
• Recurring Tasks: Parses periodic recurring tasks.
• Tag Support: Extracts and manages relevant tags.

📦 Tools

1. Extraction Tool (obsidian-tasks)

Function Description

This tool is used to extract Obsidian format task information from all Markdown files in a specified directory and its subdirectories.

Usage

Basic Usage

obsidian-tasks /path/to/obsidian-vault

Supported Options

• --recursive: Recursively traverse all subdirectories.
• --filter: Specify filtering conditions (e.g., specific tags or date ranges).
• --output-format: Set the output format (supports JSON, CSV, etc.).

Output Example

[
  {
    "id": "1",
    "description": "Complete the project report",
    "due-date": "2025-05-01",
    "tags": ["work", "report"],
    "priority": "high"
  },
  {
    "id": "2",
    "description": "Review the meeting minutes",
    "scheduled-date": "2025-04-30",
    "start-date": "2025-04-28",
    "recurrence": "weekly"
  }
]

2. Query Tool (query)

Function Description

This tool is used to search and filter the extracted task information based on specified conditions.

Supported Query Conditions

• Tags: #tag
• Time Range: due:YYYY-MM-DD..YYYY-MM-DD
• Priority: priority:high/medium/low

Example Usage

query --tag work --priority high /path/to/output.json

3. Analysis Tool (analyze)

Function Description

This tool is used to perform statistics and analysis on the extracted task data and generate reports.

Supported Analysis Types

• Time Distribution: Count the number of tasks by date.
• Tag Frequency: Analyze the occurrence times of each tag.
• Priority Distribution: Calculate the proportion of tasks with different priorities.

Example Usage

analyze /path/to/output.json --output report.html

💻 Using Docker

Build the Image

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

Run the Container

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

Claude Desktop Configuration Example

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

📚 Task Formats

The following Obsidian task formats are supported:

• Basic Format: - [ ] Task description
• Completed Tasks: - [x] Task description
• Due Date: 🗓️ YYYY-MM-DD
• Scheduled Date: ⏳ YYYY-MM-DD
• Start Date: 🛫 YYYY-MM-DD
• Creation Date: ➕ YYYY-MM-DD
• Priority: ⏫ (High), 🔼 (Medium), 🔽 (Low)
• Recurring Tasks: 🔁 every day/week/month/etc.
• Tags: #tag1 #tag2

Example:

- [ ] Complete the project report 🗓️ 2025-05-01 ⏳ 2025-04-30 🔼

📄 License

This project is open-sourced under the MIT license.

🤝 Contribution Guidelines

We welcome forks and pull requests to help improve this tool.

📞 Contact

If you have feedback or want to discuss, please contact us:

• Email: contact@jfim.com
• GitHub: https://github.com/jfim/obsidian-tasks-mcp

⚠️ Important Note

This project is still in development, and some features may not be fully functional. Please read the documentation carefully before use and back up important data.