<div align="center">

Obsidian Tasks Engine MCP

Your whole task list, one question away — answered by the real Obsidian Tasks query engine.

</div>

An MCP server that runs the real query engine of the Obsidian Tasks plugin outside of Obsidian.

Obsidian keeps your notes as plain Markdown files in a folder called a vault, and the Obsidian Tasks plugin (source) turns the - [ ] … lines in them into real tasks, with due dates, recurrence and dependencies between them. What makes the plugin worth building on, though, is its [query language]: instructions such as not done, due before tomorrow, is not blocked or group by filename, written one per line, across forty kinds of filter.

That query language is what this server hands to an AI assistant. MCP, the Model Context Protocol, is an open standard for offering an assistant tools it can call and letting it decide when to call them; here the central tool takes a Tasks query and runs it over your vault.

So the range of what you can ask for is the range of the query language itself. "What is due today, and leave out anything that still depends on another task" is one obvious example; equally possible are "which tasks under Projects/ have no due date at all", "group everything open by file and sort by urgency", "what did I finish last week", "what is scheduled for this month and tagged #work". Anything that would work in a tasks code block inside Obsidian works here.

Obsidian itself need not be running — nor even be installed. The server reads the Markdown files directly, so the vault can be queried with the app closed, on a headless server, over SSH, or from a script. And it only reads: nothing is ever written back.

Every other Obsidian Tasks MCP server we are aware of reimplements that query language in code of its own, and so supports only part of it — usually without saying which part. This one takes the opposite route: the plugin comes in unchanged as a git submodule, and its Query class is called directly. Every filter is therefore available — boolean combinations, relative dates, recurrence rules — and stays available, because keeping up with the plugin is a git submodule update rather than a reimplementation.

How that works is described below under "How it works"; why it is built this way, in docs/ARCHITECTURE.md. If you want to contribute, start at CONTRIBUTING.md.

Built and tested against obsidian-tasks 8.6.0. The submodule is pinned to an exact commit — git submodule status names it — and that pin is what the test suite runs against. The version here is checked by npm test, so it cannot quietly fall behind the submodule.

An example

You: What do I have to get done this week? Leave out anything I can't start yet or that's still waiting on something else.

The assistant turns that into a Tasks query and calls query_tasks:

not done
(due before in 7 days) OR (scheduled before in 7 days)
starts before tomorrow
is not blocked
group by filename
sort by priority

The plugin's engine runs it over the vault and the server answers with the result, fenced off as data, followed by how every line was understood (abridged):

## Matches: 6 of 11 tasks

<vault-content>
#### [[Conference talk]]
- [ ] Send abstract to the programme committee 🆔 abstract ⏫ 📅 2026-09-14
- [ ] Book train to Berlin 📅 2026-09-16

#### [[Garden shed]]
- [ ] Order timber 🆔 timber 🔼 📅 2026-09-15

#### [[Household]]
- [ ] Renew passport ⏫ 📅 2026-09-11
- [ ] Water the plants 🔁 every 3 days 📅 2026-09-13
- [ ] Call the dentist ⏳ 2026-09-12
</vault-content>

## Query as it ran

  (due before in 7 days) OR (scheduled before in 7 days) =>
    OR (At least one of):
      due before in 7 days =>
        due date is before 2026-09-19 (Saturday 19th September 2026)
      scheduled before in 7 days =>
        scheduled date is before 2026-09-19 (Saturday 19th September 2026)

  starts before tomorrow =>
    start date is before 2026-09-13 (Sunday 13th September 2026) OR no start date

  is not blocked

Assistant: Six tasks. Start with the passport — it was due yesterday and is high priority. The abstract for your talk is due on Monday, the timber for the shed on Tuesday, and the train to Berlin needs booking by Wednesday. The dentist call is scheduled for today, and the plants need watering tomorrow.

The five tasks left out were not left out by the language model. One is done, two depend (⛔) on the abstract and the timber, one does not start until the 20th, and one has no date at all — the engine decided that, exactly as it would in a tasks block inside Obsidian.

Features

• The whole query language, run by the plugin's own Query class — boolean combinations, relative dates, recurrence, dependencies, grouping and sorting.
• No silently dropped filters. Every response explains the query as the engine understood it; a line it does not understand is an error, not a smaller result.
• Reads the vault the way Obsidian does: the plugin's FileParser, your global filter, global query and custom statuses, frontmatter as real YAML — checked against real Obsidian data from the submodule.
• Read-only and bounded. Nothing is written; nothing outside the configured vault is read; -scope restricts the server to part of it.
• Two transports: stdio, or Streamable HTTP on loopback with an optional shared secret.
• Three tools: query_tasks, explain_query and tasks_query_syntax, with the same names and parameters as the Go server it replaces.
• A CLI for running queries and for --check, which verifies invariants on any vault of your own, with --summary for output that must not quote tasks.

What it does not do

Boundaries, not omissions — the reasoning is in docs/ARCHITECTURE.md under "Non-goals":

• It never writes. No completing or adding tasks, nothing in .obsidian/. Your vault is only ever read, so nothing here can damage it.
• Tasks only — not a general Obsidian API: no Dataview, no backlinks, no full-text search across notes.
• It does not invent queries. The assistant writes the query; the server runs it and explains it, and refuses what it does not understand.
• It is not a networked service. --http listens on loopback and there is no --host and no TLS; exposing a vault to a network is left to a proper reverse proxy. (An optional shared secret narrows who on the same machine may call it — that is a different, smaller thing.)
• It does not talk to Obsidian. The vault on disk is the whole interface.

Those boundaries are mostly there for one reason: a vault is private. Medical appointments, salaries, other people's names. So the server reads only below the roots it was given — a symbolic link pointing out of the vault is skipped, not followed, and a call may not name a directory outside them unless a person allowed that at the command line. It returns tasks and nothing else from the files it reads, says its problems in the vault's own terms rather than in absolute paths, marks everything that came out of the vault as read data rather than as instructions, never evaluates JavaScript from a query unless a human turns it on at the command line, and never writes. -scope narrows it to part of a vault, --summary keeps task text out of anything that gets logged. The full risk model — what could go wrong and which code prevents it — is in docs/ARCHITECTURE.md under "Security is a goal of the same rank as correctness". Found a way around it? Please report it privately, as described in SECURITY.md.

What is open, as opposed to ruled out, is in docs/TODO.md — itself written in the Tasks format, and queryable with the server.

Setup

git clone --recurse-submodules https://github.com/Cito/obsidian-tasks-engine-mcp.git obsidian-tasks-engine-mcp
cd obsidian-tasks-engine-mcp
npm install
npm run build

If you have already cloned without it, fetch the submodule afterwards:

git submodule update --init --depth 1

--recurse-submodules is not optional, and GitHub's "Download ZIP" does not include submodules. A ZIP, or a plain git clone, leaves vendor/obsidian-tasks empty and the build fails immediately — the submodule is the engine. Use the clone command above.

dist/ is not in the repo (see .gitignore). After a fresh clone and after every git pull, npm install && npm run build has to have run, or dist/server.js will not be there and the server will silently fail to start.

This is all that setup is, for both ways of running the server below: the build produces dist/server.js, and how it is then reached — started by the client over stdio, or running as a service on a port — is a matter of configuration, not of installing anything further.

Usage

As an MCP server

It offers three tools:

| Tool | Parameters | Purpose | |---|---|---| | query_tasks | rootDirs?, filters, includeDetails? | Run a query | | explain_query | rootDirs?, filters | Only check and explain a query, without reading the vault | | tasks_query_syntax | — | Look up every available instruction, generated from the submodule's documentation |

Every response contains the explanation of the query and the vault settings in force. A line that was not understood leads to an error response — never to a silently reduced result.

There are two ways to run it, and they differ only in how the client reaches the server — the same three tools, the same answers, the same vault:

| | stdio (default) | HTTP (--http) | |---|---|---| | Who starts the server | the client, as a subprocess | you, before the client connects | | Configured with | a command line | a url | | Lifetime | as long as the client runs | long-lived; several clients can share it | | rootDirs from a call | only the -root directories | only the -root directories | | Opening that up | --allow-any-root | not possible |

Use stdio unless something rules it out — it needs no process management and nothing listening on a port. HTTP is for the cases where the client cannot spawn a subprocess (a container, a remote or web-based client, anything that only accepts a URL), or where several clients should share one server.

Over stdio

This is the default and needs no flag. The client starts the server itself, so there is nothing to launch or keep alive:

node dist/server.js -root /path/to/vault -root /path/to/second-vault
node dist/server.js -root /path/to/vault -scope Subfolder/

Most clients are configured with a block like this:

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

Call shape, tool names