Back to Browse

Obsidian MCP Server

ProductivityLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

Self-hosted agent memory in an Obsidian vault: hybrid search, link graph, tasks, safe writes, OAuth

About

Self-hosted agent memory in an Obsidian vault: hybrid search, link graph, tasks, safe writes, OAuth

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (1 strong, 1 medium validity signals). No known CVEs in dependencies. Imported from the Official MCP Registry.

3 files analyzed · No issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

PostgreSQL 16 + pgvector (0.8.0+) connection URL for the app's NON-superuser role, e.g. postgresql+asyncpg://obsidian_mcp:<password>@postgres:5432/obsidian_mcp. A superuser role or a CHANGE_ME password is refused at startup.Required

Environment variable: DATABASE_URL

Path of the Obsidian vault inside the container (mount your vault read-write there).Optional

Environment variable: VAULT_PATH

itsdangerous signer for cookies/sessions. Generate with `openssl rand -hex 32`; the app refuses to start on a placeholder.Required

Environment variable: SECRET_KEY

Public hostname your reverse proxy routes to. Also derives BASE_URL, ALLOWED_ORIGINS and ALLOWED_HOSTS as https://<MCP_HOSTNAME> unless those are set explicitly.Optional

Environment variable: MCP_HOSTNAME

Embedding provider: `ollama` (self-hosted, default), `openai` (bring your own key) or `tei` (Hugging Face Text Embeddings Inference, native /embed). Switching after deploy requires `make reset-embeddings`.Optional

Environment variable: EMBEDDING_PROVIDER

Ollama endpoint serving bge-m3 (used when EMBEDDING_PROVIDER=ollama). Must be https or loopback unless EMBEDDING_ALLOW_PLAINTEXT is set.Optional

Environment variable: OLLAMA_URL

OpenAI (or OpenAI-compatible) API key for text-embedding-3-* (required when EMBEDDING_PROVIDER=openai; the server refuses to start without it).Required

Environment variable: OPENAI_API_KEY

TEI endpoint (used when EMBEDDING_PROVIDER=tei). Must be https or loopback unless EMBEDDING_ALLOW_PLAINTEXT is set.Optional

Environment variable: TEI_URL

Must equal the model_id the TEI server reports at GET /info, exactly (a local path included); a different value refuses startup. A change needs `make reset-embeddings`.Optional

Environment variable: TEI_EMBEDDING_MODEL

Inputs per TEI /embed request (1-256). A value above the server's max_client_batch_size refuses startup.Optional

Environment variable: TEI_EMBED_BATCH_SIZE

Bearer token for a TEI server started with --api-key; sent only to TEI_URL (/embed, /info, the panel's /health). Empty means no Authorization header.Required

Environment variable: TEI_API_KEY

How to Install

Install command not verified. See the repository for install instructions.

View repository

Documentation

View on GitHub

From the project's GitHub README.

Obsidian MCP Server

Python License MCP PostgreSQL

Your agents' memory, in the vault you already have, reachable from claude.ai, ChatGPT, Claude Code and your phone.

A self-hosted Model Context Protocol server that turns an Obsidian vault into long-term memory for every agent you use. Agents search it by meaning or by exact words, follow its wikilinks, see what changed since their last session and who changed it, keep their to-dos in it, and write back through guarded, atomic edits. 33 tools over plain markdown files that you can open, edit and grep.

What sets it apart:

  • Your existing vault, served in place. No imposed note format, no sidecar syntax, no "memory" folder you have to adopt. Agents read what you read, follow your wikilinks, and pick up your folder layout, frontmatter schema and tag conventions from the vault itself.
  • Remote and multi-user. OAuth 2.0 PKCE and API keys, so claude.ai, Claude Desktop, Claude mobile, ChatGPT, Claude Code and n8n all read and write the same files, each user confined to their own vault root.
  • Writes are guarded. An edit that carries expected_hash is refused when the note changed since it was read, and a deployment can require the hash on every edit (Guarding edits against stale reads). Every publish is atomic, a create refuses a path that is already taken, deletes go to .trash/, and dry_run returns the diff before anything lands.

Connect from Claude Code:

claude mcp add obsidian --transport http \
  --url "https://obsidian-mcp.<your-domain>/mcp" \
  --header "Authorization: Bearer omcp_..."

In claude.ai, Claude Desktop or ChatGPT, add a custom connector at https://obsidian-mcp.<your-domain>/mcp and sign in through the OAuth consent page. Connect a client has the rest.

Stack: Python 3.12, FastAPI, PostgreSQL with pgvector, and an embedding backend of your choice (Ollama, OpenAI or Hugging Face TEI; see Pick an embedding backend).

Dashboard

Contents

Why this exists

There are three things going on here, and they're more interesting together than apart.

1. Agent memory that you can actually read

If you let an agent run for a while, it needs memory. Most setups solve this with an opaque vector store, a SQLite blob, or a managed "memory" service that you can't see into. That works until you want to know what the agent thinks it knows about you, or you need to correct something, or you want to understand why it just made a weird suggestion.

This server gives you a different deal. Agent memory lives as markdown files in your vault. Folder structure, file names, frontmatter, all visible. You can open the file in Obsidian and read it. You can edit it. You can delete it. You can grep it. The agent's "memory" is a human-auditable artifact that sits in the same place as your own notes, with the same tools available.

The home lab is the use case that sold me on this. My vault has notes on the rack, the network, and every Home Assistant integration. I can say "set up a night-light mode in the master bathroom, 1% after 11pm" and a sysadmin agent finds the right config, makes the change, and updates the doc in the same pass. Six months later when I've forgotten how it works, the answer is in the vault, not buried in some chat history I can't search.

The semantic search and wikilink graph still work over that material, so retrieval is fast and conceptual. But the substrate is files you own, not a black box.

To be precise about the scope: what the server supplies is MCP-accessible storage, keyword and semantic search, and graph operations over markdown notes, for whatever MCP clients you connect. The agents direct their own reads and writes. There is no extraction or decay pipeline running behind them, and nothing rewrites a note because a model judged it stale: an agent remembers something because it wrote a note, and forgets it because someone deleted one. By late 2026 that is less of a contrarian position than it sounds. Every vendor's consolidation step (the "dreaming" or "sleep-time" job) has turned into a separate process you can inspect, rather than silent extraction inside the write path. This server keeps the agent as the author. The consolidation help it will grow is a hygiene report that proposes merges and flags duplicates, and never writes (#359), not a pipeline that edits your notes while you are not looking.

2. A shared memory layer between you and your agents

The other half runs the other way: the vault isn't only the agents' memory, it's mine. I think of my Obsidian vault as my exocortex. The "big me" that includes notes, calendars, scripts, search, and AI assistants is substantially more capable than the "small me" of the biological brain alone. It's also where I do most of my thinking, because writing something down is itself a form of thought.

The problem is that until recently, the vault was passive. I had to go find things. Agents that wanted to help me had to be briefed from scratch every session, and they had no way to see what I'd already written about a topic.

This server fixes that. Now the same vault feeds my own daily writing and any agent I plug into it. The agent reads what I read, links what I link, follows the same wikilinks, sees the same frontmatter. When I write a project note on Sunday, my Monday-morning briefing agent already knows about it. When the agent leaves notes from a research session, they show up in my normal Obsidian search.

A concrete version of this: I'll spend a session in Claude Code on a project, wrap up, push the commits, and then just say "update Obsidian." The agent reads the vault guide, figures out where project notes live in my structure, picks the right format and frontmatter, and leaves a session log I can later roll into a status report. No path-passing, no telling it what to write — the conventions are already in the vault, and it follows them.

The same goes for commitments. My to-dos are checkbox lines in those notes, and the task tools let an agent read the same list I do: what is overdue, what is due this week, what I am waiting on from someone else. It can add a follow-up from a conversation or tick one off when the work is done, and the change is one line in a file I can see. That part is optional. Plenty of vaults hold no tasks at all, and nothing else depends on it.

That's the exocortex idea made concrete: one place that holds context, and both the human and the agents reading and writing into it on the same terms.

3. The vault follows you

The thing that still surprises me is that this is internet-facing. Same vault, same notes, reachable from anywhere I happen to be talking to an agent — Claude in a browser tab, Claude on my phone on the train, an n8n workflow firing on a schedule, a Claude Code session on whatever laptop is in front of me. All behind OAuth or a bearer key, all hitting the same source of truth.

So when I hear an interesting podcast on a commute and want to think out loud about it with Claude on my phone, the agent isn't starting cold. It can pull up what I've already written on adjacent topics, surface a note I half-finished six months ago, and at the end of the conversation suggest updates and write them in. The vault doesn't have to be near me to be the thing I'm working in. (A session away from the keyboard walks through exactly one of these.)

A session at the keyboard

To make the abstract concrete, a short transcript from a real session. Tool calls inline; the user types in plain English and the agent picks the right tool.

you  > find anything I've written about why retrieval-augmented
       chat is hard

claude
  → semantic_search(query="why retrieval-augmented chat is hard")
    • 2025-12-03 - RAG failure modes.md
    • 2025-10-18 - Chunking tradeoffs.md
    • 2024-06-22 - Vector recall vs precision.md

  the closest hit is your December note on RAG failure modes. let
  me see what it's connected to.

  → get_neighborhood(path="2025-12-03 - RAG failure modes.md",
                     depth=1)
    8 connected notes. notable ones:
    • "Hybrid search" — a re-ranking design you sketched but
      didn't ship
    • "Out-of-distribution queries" — a half-finished draft from
      October
    • "Embedding model choice" — links to bge-m3, your current
      model

  you have three connected pieces here: a failure-modes catalog,
  an unshipped hybrid-search sketch, and an abandoned O-O-D draft.
  want me to summarize all three together, or pull up the draft
  so you can decide whether to finish it?

you  > pull up the draft, and tag it #revisit-2026 in frontmatter
       while you're there

claude
  → read_note(path="2025-10-18 - OOD queries (draft).md")
  → set_frontmatter(
      path="2025-10-18 - OOD queries (draft).md",
      updates={"tags": ["draft", "rag", "revisit-2026"]}
    )

  here's the draft, and the tag is on. you stopped right before
  the section on confidence thresholds; the open question you
  left yourself was…

Two things to notice. First, the agent didn't need to be told what folder to look in or what tools to use — it picked them. Second, the write at the end is structured (set_frontmatter mutating YAML, not a regex over the file body), so the note round-trips cleanly. The self-describing vault and the wikilink graph are doing the work that makes this feel natural.

A session away from the keyboard

The transcript above is the easy case: I'm at a desk, I can see what the agent is doing, and Obsidian is one alt-tab away. The session that actually changed how I think about this server had none of that.

I was out walking with a health podcast in my ears — a long one, two people who clearly disagreed with each other, an hour of it. I had my phone and no intention of going home to a laptop. So I pulled the episode's transcript, handed it to Claude on my phone, and we talked it through while I kept walking: what the actual claim was, which parts I already had notes on, where it cut against something I'd decided months ago and written down at the time.

The agent had the vault the whole way. It surfaced what I'd already written on the topic, flagged that two dates in an older note were wrong, and asked whether a decision I'd recorded last year still stood given what the episode argued. By the time I got back it had written all of it in: the health-related decisions I'd actually landed on during the walk, the date corrections in the old note, a couple of new notes on the episode itself — and, because the conversation kept circling back to it, a durable note on how I decide which experts to trust on medical questions in the first place. That last one is the artifact I keep returning to. It wasn't about the episode at all; it was the reasoning underneath a whole class of decisions, and it now sits in the vault where the next agent will find it.

I never opened Obsidian. Not on the walk, not when I got home. The whole session — retrieval, argument, correction, and the writing that came out of it — went through an agent, and the vault is simply where it landed. Obsidian is how I check the work afterwards, not how the work gets done. That inversion is most of the reason this project looks the way it does.

What's in the box

The server exposes 33 MCP tools across six families, plus the auth and ops layer around them.

Every tool is published with a title and MCP ToolAnnotations, all four hints set explicitly: readOnlyHint on the nineteen tools that only read (search, read, list, graph, list_tasks, task_agenda, get_changes, check_upload), destructiveHint on the eleven that can replace or remove something (edit_note, move_note, delete_note, set_frontmatter, write_file, delete_file, import_from_url, complete_task, update_task, move_task, and request_upload, whose link can overwrite on redemption), openWorldHint on import_from_url only. create_note, add_task and request_download are additive. Clients that honour annotations run read-only tools without a per-call confirmation (Claude Code also runs them in parallel) and keep prompting on destructive ones. They are hints: the server enforces read-only credentials itself, regardless of what a client does with them. The initialize result also carries a short instructions paragraph — what the vault is, which tool to reach for, and the write-safety rules — for clients that load only tool names at session start. No description exceeds 4,000 characters on the wire, so none is cut off by a client's description limit.

Search and discovery

  • keyword_search(query, folder?, tags?, frontmatter?, limit=20), full-text via PostgreSQL tsvector. A note's title and frontmatter aliases rank above its body, so a query that is a note's title finds that note first; its tags (frontmatter and inline #tags, a nested #a/b also as a and b) are indexed below the title and above the body, and matched_in names which of title, tags and body matched; bare terms are ANDed, and when the full matches do not fill the page, partial matches follow tagged match: any; every row carries a snippet: with the matches highlighted (or head:, the note's opening words, for a title or tags match). The text-search config(s) are configurable via FTS_CONFIGS (see Full-text search language(s))
  • semantic_search(query, folder?, tags?, frontmatter?, limit=15, rerank=false), vector similarity via pgvector, one one-line preview chunk per note. Notes are chunked at their headings, and each chunk is embedded under a Title > Heading > Subheading context prefix. A fresh row names the section it matched: § "Plan/Risks" (#7) or § (top of note), and read_note(path, section="#7") reads exactly that section. Previews start on a word; a section too short to stand alone (under 200 characters) is grouped with its neighbour, so a preview can include an inner heading line and its § names the enclosing section. Stale rows, and rows not yet re-embedded since the upgrade to heading-aware chunks, carry no locator. While any of your notes is still on the old chunking, each response says so on an index_transition: line under its header
  • hybrid_search(query, limit=10, folder?, tags?, frontmatter?, rerank=false), both of the above fused by reciprocal rank fusion over each arm's top 50, one line per note with its fused score, each arm's rank and the 1/(k+rank) terms behind the score. The three are peers, and every description carries the same routing sentence: exact identifiers, code symbols, titles or known phrases go to keyword_search; conceptual or paraphrased questions to semantic_search; unsure which, hybrid_search. A single arm can beat the fusion on its own kind of query. If the embedding provider is down, hybrid_search returns the keyword ranking marked arms: keyword-only (semantic unavailable: …), never silently degraded: the marker is on every return path, so a keyword-only page cannot pass for a fused one.
  • Every page of semantic_search and hybrid_search carries a confidence: ok | low header token. low means no keyword note matched all the terms and the closest semantic candidate is under SEARCH_LOW_CONFIDENCE_SIMILARITY, with a one-line hint to try keyword_search or get_neighborhood when it costs no row. Nothing is filtered. The threshold ships at 0 (off: always ok) until you calibrate it.
  • rerank=true on either of the last two asks an optional, operator-configured reranker (RERANK_URL) to reorder the candidates the call already fetched (at most 50 notes). Each note is scored on the best of up to four of its fetched chunks, sent as the same text they were embedded from (title, heading path and tags, then the chunk); a reranked row's preview and § locator show the chunk that scored. The response is either fully reranked (reranked: true (candidates: N), a rerank_score per row) or the unreranked page marked reranked: false (<reason>); without a reranker it answers reranked: false (not_configured). Its rows are one-line quoted objects, like hybrid_search's
  • list_notes(folder?, limit=50, since?, until?, order_by?, cursor?), sorted by modified time
  • get_recent(folder?, limit=20, since?, until?, order_by?, cursor?), recently changed, with each modification time in UTC (YYYY-MM-DD HH:MM UTC). On both, order_by="content_changed" with since lists notes whose content changed (a touch or a re-sync that keeps the bytes does not count); since is inclusive and until exclusive, each a UTC date (YYYY-MM-DD, the whole day) or an ISO 8601 datetime with an explicit offset. Any of the four switches to keyset paging with a more: cursor=… footer; a call with none of them is unchanged
  • get_changes(since, folder?, kinds?, by="any", limit=50), the change feed: one line per note created, modified, moved or deleted after a cursor, oldest first, each attributed to the API key or OAuth client that made it ((you) for your own credential) or human/sync for an edit the index discovered (Obsidian, a sync client, git). It returns next_since, an exact ev:<n> cursor an agent stores in its own notes for the next session; by is any | me | agents | human. Deletions say why (removed, not_indexable, quarantined); gap and reset lines say when the view is incomplete
  • get_tags(limit=50), tag and count
  • list_tasks and task_agenda list checkbox tasks across the vault from the index; see Tasks (optional)
  • get_vault_guide(), the Obsidian primer plus this vault's CLAUDE.md, served live
  • Retrieval changes are measured with make search-eval against judgments mined from the operator's own usage log (a search followed by a read of one of its results); see the search evaluation harness

Read and write

  • read_note(path, section?, offset=0, limit?) returns a structured result — path, title, tags, frontmatter_yaml and a JSON frontmatter view, heading (section reads), content, and truncation as data (truncated, offset, next_offset, total_chars, outline, notice). Bounded by MAX_READ_RESPONSE_CHARS (default 40,000) — see Response size limits. section=<heading> returns one section's body instead of the whole note; offset continues a truncated read.
  • create_note(path, content), atomic write, refuses overwrite
  • edit_note(path, …) with four mutually exclusive modes: full replace (default), append=True, find=… (with optional replace_all), or section=<heading> (ATX headings, supports Parent/Child path-style and #N ordinal disambiguation). dry_run=True returns a unified diff without writing. Legacy clients may use operation="append"; operation="replace" explicitly selects full replace.
  • move_note(from_path, to_path, rewrite_links=False), relocates and optionally rewrites incoming [[Old]], [[Old|alias]], [[Old#anchor]], ![[Old]], and [[folder/Old]] references in source notes
  • delete_note(path, permanent=False), soft-delete to .trash/<YYYYMMDD-HHMMSS>-<basename>-<8 hex> by default, via a single non-replacing rename, so it never overwrites an existing trash entry (a filesystem that cannot do that rename makes the soft delete refuse with a named error rather than fall back). permanent=True unlinks.
  • set_frontmatter(path, updates, remove?), structured YAML mutation. Body is byte-identical when only frontmatter changes.

Tasks (optional)

An agent that keeps notes usually also keeps commitments: a follow-up it promised, a next action, something to check again on Friday. These five tools let it keep them as checkbox lines in the same vault as its notes, and find, add and close them without reading files. Nobody has to use them. A vault without checkboxes behaves exactly as before, and no other tool depends on them.

What counts as a task. By default, any markdown checkbox list item: - [ ] Renew the certificate, * [x] …, 1. [/] …, including one inside a blockquote or callout, or indented under another item. A plain checkbox is a complete task, and Obsidian does not have to be installed. A vault whose checkboxes are not all tasks can narrow this with a task rule; see Which checkboxes are tasks. The optional fields use the Obsidian Tasks plugin's emoji format, so the same notes also work in Obsidian, with or without that plugin:

FieldWritten as
due📅 2026-11-20
scheduled⏳ 2026-11-18
start🛫 2026-11-15
priority🔺 highest, ⏫ high, 🔼 medium, 🔽 low, ⏬ lowest
recurrence🔁 every week
done✅ 2026-11-10
cancelled❌ 2026-11-10
created➕ 2026-11-01

[ ], [/] and every other marker are open, [x] and [X] are done, and [-] is cancelled. A checkbox inside a code block is not a task, and a Tasks-plugin query block (```tasks) is text the server does not evaluate. The server supplies the mechanics (listing, one-line edits, moving a task between notes, and recurrence for the rules listed below) and no policy: where tasks live, what a tag means and what is due when are up to you, your agents and your vault guide.

Which checkboxes are tasks. A checkbox is not always a task. People use checkboxes for checklists, runbooks, verification steps, acceptance criteria, packing lists, meeting agendas and the step lists inside work tickets. None of those is a commitment someone has to act on, but a tool that treats every unchecked box as an open task reports them all.

This matters more in a vault that AI agents write into. Agents produce checkbox lists freely: a plan, a step-by-step procedure, the "done when" criteria of a ticket, a status note. Each list adds open "tasks". An agent that asks "what is on my plate" then gets an answer made mostly of procedure steps; a text search for a task also matches the same words in a runbook; and add_task's duplicate check refuses a new task, or lists "similar tasks", because of a checklist line that was never a task. In one real vault, 1,868 checkboxes were open: 314 were tasks and 1,554 (83%) were not. In that vault's dedicated task lists, every open checkbox carried a date, a priority, a recurrence rule or a workflow tag. The plain checkboxes sat in the same folders and often the same notes as the tasks, so excluding folders or note tags could not separate them.

So each user (in single-user mode, the server) has a task rule that says which checkboxes count as tasks:

RuleA checkbox is a task whenChoose it when
all (default)alwaysYour checkboxes are your tasks, for example a small agent-memory vault.
fieldsit carries a task field (a due, scheduled, start, created, done or cancelled date, a priority or a recurrence rule) or one of your task tagsYour real tasks carry a date, a priority or a tag such as #waiting, and your checklists do not.
filterits text contains your global filter text, such as #taskYou mark every task with one marker, or you already use the Tasks plugin's "Global task filter".

Task tags match the way list_tasks(tags=…) does: ignoring case and by / segment, so the task tag waiting matches #Waiting/bob but not #waitingroom. The global filter is the Tasks plugin's own mechanism: a plain text match that respects case, anywhere on the line. #Task does not satisfy #task, while #tasks and a #task inside inline code do; the filter does not have to be a tag (TODO works).

The default stays all for three reasons: plain checkboxes keep working for a vault whose checkboxes are its tasks; it is what the Tasks plugin does when no global filter is set; and an existing deployment sees no change until someone picks another rule (under all every response is byte for byte what it was before). A vault that agents write into should choose fields or filter, and say in its vault guide (the vault's CLAUDE.md, served by get_vault_guide) how a task is written, for example "every task has a 📅 due date or the #waiting tag" or "every task line contains #task". Agents then create tasks the rule recognises. add_task helps: under filter it adds the filter text itself, and under fields it says when the line it wrote is not a task.

The rule is chosen on the panel's Tasks card, or for everyone without a choice of their own by TASKS_RULE, TASKS_RULE_TAGS and TASKS_GLOBAL_FILTER (see Configuration). It applies to the default scope only: default listings from list_tasks and task_agenda, and add_task's duplicate check across the index. Nothing is hidden silently. While fields or filter is in force, a default-scope response carries one more header line, for example:

Rule — task rule: filter "#task" — excluded by rule: 2 tasks — kept though unsure (text cut): 1 tasks — pass scope="all" to list every checkbox

It names the rule, counts the checkboxes the rule left out (excluded by rule, apart from excluded by scope, which counts the folder and note-tag exclusions), and counts the ones kept only because the server could not judge them: a line whose stored text was cut at 1,000 characters before the filter text appeared, or whose tags were cut past 64. Those are listed rather than hidden. scope="all" lists every checkbox, whatever the rule. Under fields, while rows still await the first index pass after an upgrade, the line also says the rule is approximate for them. A stored rule the server cannot apply (only a manual database edit can produce one) is treated as all, and the line says so.

Writes under a rule. The rule never blocks a write: complete_task and update_task address any checkbox by path and id, including one that only scope="all" lists.

  • Under filter, add_task puts the filter text at the start of the new task's text when the line does not already contain it, as the Tasks plugin's own task dialog does, and the response adds global filter added: "#task". A text that would pass 1,000 characters with the filter added is refused, with nothing written.
  • Under fields, add_task writes a line with no field and no task tag as asked, and the response adds note: not a task under your task rule "fields" …: default listings will not show it. update_task adds the same note, under fields or filter, when its edit leaves a line that is not a task by the rule, for example after removing the last date or the filter text. update_task never adds the filter text back.
  • add_task's check against the note it writes into still compares every open checkbox in that note: the same words in the same note are most likely the same thing (update_task can give that line a date; allow_duplicate=true adds anyway).
  • Under filter, the duplicate check recognises an existing task whether its filter text sits in front (where the server puts it) or as a trailing tag (where people usually put one): add_task(text="Renew passport") is refused as a duplicate of Renew passport #task.

A list_tasks cursor is refused (invalid_argument) once the rule changes in a way that changes the rows (another rule, other task tags under fields, another filter text under filter); list again.

ToolWhat it does
list_tasksLists tasks from the index without reading a note. Filters: status, folder, path, tags and excluded tags, due / scheduled / done date ranges, undated, priority, words in the text, recurring. Ordered by due date, priority, scheduled date, done date or path, and paged with a cursor. Every row carries the task's id.
task_agendaA dated overview from the index: overdue, due today, scheduled and now due, and due in the next days days (default 7). Every section states its count, and a section that is cut short ends with the exact list_tasks call that continues it.
complete_taskMarks one task done ([x], plus ✅ <date> by default) and, for a recurring task, writes its next occurrence in the same edit.
update_taskChanges one task's dates, priority, tags, recurrence, status (open, in progress, cancelled) or description, or adds one context line under it.
add_taskInserts one new - [ ] line into an existing note, after the last top-level task of the note or of a named section and everything indented under it.
move_taskMoves one top-level task, with every line indented under it, to another note or section, byte for byte. The destination is written before the source, so an interrupted move leaves the task in both notes, and resume=true completes it; an outside save of an older destination during the move can still lose the task.

The four write tools need write permission, like every other write. list_tasks and task_agenda read the same index as the search tools, and the header of every response counts what the index could not show (notes not yet scanned, tasks that could not be indexed, notes over the 5,000-task cap), so an empty list never silently means "nothing open".

Task ids. Every listing row prints the task's id, a 12-character key computed from the task's text. To change a task, pass the note's path and that id. The server finds the line by recomputing the ids from the note's current text, never from a stored line number, and because a write changes the line's text, the response returns the task's new id. Nothing is ever written into a note to identify a task. Pass the path as it is on disk: a row escapes unusual characters in a path (a tab as \t, a backtick as \u0060, a backslash doubled), so undo those escapes if the row shows any. When a note holds several identical task lines, their ids carry an occurrence suffix (3f9a0c1b2d4e.2of3), and a write with such an id also needs the note's content_hash from read_note as expected_hash.

What a write guarantees.

  • One line changes. Only the characters of the field being changed are touched. The rest of the line (indentation, list marker, field order, spacing) and every other line stay byte for byte. The only extra lines are the ones the call asks for: a recurring task's next occurrence, the new line from add_task, or one context line. Each planned edit is re-parsed and checked before it is written.
  • Refused rather than guessed. Each of these is refused with nothing written, and the refusal ends with one MCP-REFUSAL line carrying its code: an id that no longer matches any line (task_not_found: list again), a bare id that matches several lines (task_ambiguous), a field the call changes that appears twice on the line (task_malformed), an unsupported recurrence rule (recurrence_unsupported), and on add_task an open task with the same description (duplicate_task; allow_duplicate=true adds it anyway). add_task also lists up to five similar open tasks, which never block.
  • dry_run=true returns the diff and the new line(s), and writes nothing. expected_hash is optional and binds the whole note, as on edit_note. Without it, a change made by someone else during the call is retried from a fresh read, at most 3 attempts in total.
  • Listings see the write at once. A successful write refreshes that note's task rows in the index (index: refreshed). If the refresh cannot run, the write still stands and the response says index: may lag (<reason>) until the next index pass. edit_note, set_frontmatter and write_file also try to refresh the task rows of a note they change, and delete_note removes a deleted note's tasks; their output does not say whether that worked. A new note created by create_note, write_file, an import or an upload, links rewritten by move_note, and any refresh that could not run show up after the next pass (every 300 s by default).

Recurrence: the supported rules. N is a whole number from 2 to 999, weekday and month names are written out in full English, and any rule may end in when done, which counts the next date from the completion date instead of the task's own date:

  • every day, every N days
  • every weekday (Monday to Friday)
  • every week, every N weeks
  • every week on Monday, Thursday or every Monday, Thursday
  • every month, every N months (a day the month lacks becomes its last day: January 31 → February 28)
  • every month on the 15th (for the 29th to 31st, a month without that day is skipped), every month on the last
  • every year, every N years
  • every March on the 3rd

Every other rule is refused with recurrence_unsupported and nothing written, wherever it appears: completing the task, update_task(recurrence=…) or add_task(recurrence=…). That includes every weekend, every 2 weeks on Monday, every month on the last Friday, every 1 day, abbreviated names, until …, for N times, and a yearly rule on a task dated February 29. A recurring task is never completed without its next occurrence. To complete one whose rule is refused, clear the rule first (update_task(clear=["recurrence"])). The next occurrence keeps the task's text, tags and priority. Its due date (or scheduled, or start date, if it has no due date) moves by the rule, and its other dates keep their distance from it. As in the Tasks plugin, missed occurrences are not skipped: a weekly task completed three weeks late gets its old date plus 7 days, which may already be past.

Dates and the timezone. Every date argument accepts YYYY-MM-DD and relative forms such as today, tomorrow, yesterday, +7d or -1d (up to 3,660 days either way). "Today" is the current date in the caller's task timezone: TASKS_DEFAULT_TIMEZONE (default UTC), or the timezone saved on the panel's Tasks card. Every response that resolved a relative date states the timezone and the dates it used. A list_tasks cursor from a relative-date query is refused after midnight in that timezone, because the dates moved; list again.

The default scope. list_tasks, task_agenda and add_task's duplicate check across other notes work in the caller's default scope: the whole vault minus the excluded folders and excluded note tags saved on the panel's Tasks card, and only the checkboxes that are tasks under the caller's task rule. With nothing saved, which is the default, nothing is excluded. scope="all" ignores the exclusions and the rule, and every listing states its scope and how many tasks the scope and the rule left out, so an exclusion is never silent.

Not modelled: custom status cycles (completing a task with any open marker writes [x]), task dependencies, the plugin's "remove scheduled date on recurrence" setting, and its "remove global filter from description" display option (the filter text stays part of the task's text and, when it is a tag, of its tags, so with #task as the filter list_tasks(tags=["task"]) matches every task). A task with 🏁 delete is refused on completion (on_completion_unsupported) rather than deleted. The settings are under Configuration and the panel card under Tasks settings.

File access (non-markdown)

Raw read/write/browse of arbitrary vault files (PDFs, images, skill assets, data files) — distinct peers to the note tools, which stay markdown-only. Pure byte transport: no server-side PDF/text extraction, no embedding or indexing of non-markdown files.

  • read_file(path, encoding="auto", offset=0, limit?), returns text-like files as text, images as an inline image block that renders in-client, and other binaries as a base64 string. text/base64 force the form. Refuses files over MAX_FILE_READ_BYTES (default 10 MB); text results are additionally bounded by MAX_READ_RESPONSE_CHARS and continue via offset. hash_only=True returns the whole file's content_hash without content; base64 results include that hash in their header. Text results remain plain text.
  • write_file(path, content, encoding="base64", overwrite=False), lands a file in the vault; base64 for binary, text for UTF-8. No-clobber by default, auto-creates parent dirs, atomic write. Capped at MAX_FILE_WRITE_BYTES (default 25 MB).
  • list_files(folder=".", pattern="*", recursive=False, limit=200), ls-style browse of files and subdirectories with size and mtime, glob-filterable and result-capped.
  • delete_file(path, permanent=False), soft-deletes a non-markdown file to .trash/<YYYYMMDD-HHMMSS>-<basename>-<8 hex> with a single atomic rename. Refuses markdown (that is delete_note), directories, and symlinks.

All four reuse the path-traversal guard and exclude any path with a component starting with . (dot-directories and dot-files) (.obsidian, .git, .trash, …), matching the indexer's visibility rule.

Guarding edits against stale reads

Pass a read's content_hash as expected_hash when editing, updating frontmatter, moving or deleting a note, overwriting a raw file, or deleting a raw file. The canonical token is sha256:<64 lowercase hex>, computed over the complete raw file bytes; a section or truncated read_note still returns the whole-file hash. For raw files, use read_file(hash_only=True) or the base64 header. Do not hash the returned text yourself.

Documentation truncated — see the full README on GitHub.

Reviews

No reviews yet

Be the first to review this server!