obsidian-writer-mcp
Provides tools for interacting with Obsidian vaults, including creating and appending notes, managing lists, handling tasks (create, list), and sending content to an inbox, via the obsidian-writer HTTP service.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@obsidian-writer-mcp create a task for dentist appointment tomorrow high priority"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
obsidian-writer-mcp
MCP server for writing to Obsidian through the obsidian-writer HTTP service.
This project was originally created for personal use in my homelab. I later decided to publish it in case it is useful to other people building similar local-first Obsidian automation.
Related project: obsidian-writer, the HTTP service this MCP server calls to write into Obsidian vaults.
Configuration
The server reads environment variables from the process and from .env files. Existing process variables take precedence over .env values.
Load order:
.envnext toobsidian_writer_mcp.py.envin the current working directory
Create a local .env from the example:
cp .env.example .envVariables:
OBSIDIAN_WRITER_BASE_URL: base URL for the HTTP writer. Default:http://obsidian-writer:3000.OBSIDIAN_DEFAULT_VAULT: default vault used when a tool does not receivevault. Default:default.
Example:
OBSIDIAN_WRITER_BASE_URL=http://obsidian-writer:3000
OBSIDIAN_DEFAULT_VAULT=my-vaultThe .env file is ignored by Git; publish .env.example and keep local values private.
Related MCP server: Obsidian MCP Tool Server
Hermes registration
If this repository is mounted inside the Hermes container at /srv/apps/obsidian-writer-mcp, register it without hardcoded vault values; the MCP will read .env itself:
docker exec -it hermes hermes -p <profile> mcp remove obsidian-writer || true
docker exec -it hermes hermes -p <profile> mcp add obsidian-writer \
--command sh \
--args -lc 'exec uv run --with fastmcp --with httpx python /srv/apps/obsidian-writer-mcp/obsidian_writer_mcp.py'
docker exec -it hermes hermes -p <profile> mcp test obsidian-writerIf your obsidian-writer service is not reachable as http://obsidian-writer:3000 from inside Hermes, change OBSIDIAN_WRITER_BASE_URL in .env.
Tools
Inbox
obsidian_append_inbox: append one line to today's inbox file in the configured default vault.obsidian_read_inbox: read inbox items for a specific day. Thedateargument is optional; when omitted,obsidian-writeruses today's date.
Lists
obsidian_list_lists: list existing Obsidian checklist files.obsidian_list_add: add unchecked items to a named list.obsidian_list_remove: remove items from a named list.obsidian_list_update: update/rename items in a named list.
Notes
obsidian_list_notes: list existing notes.obsidian_read_note: read a note by slug.obsidian_create_note: create a new standalone Markdown note.obsidian_append_note: append Markdown content to an existing note.obsidian_create_or_append_note: create a note or append to an existing compatible note.
Tasks
Task creation keeps its existing tool name: obsidian_create_task.
Task listing is available as obsidian_list_tasks and reads structured tasks through GET /tasks.
Creation sends structured JSON to POST /tasks; it does not format Obsidian Tasks Markdown itself. The canonical formatter is the obsidian-writer service.
Supported creation fields include:
vaulttitlecontent(legacy fallback fortitle)status:todo,done,cancelleddue,scheduled,start,done,cancelled: dates asYYYY-MM-DDpriority:highest,high,medium,low,lowest,nonerecurrencetagssourcedue_text(legacy; ignored whendueis provided)depends_on(accepted by the MCP for compatibility, but not sent yet)
Dependencies are reserved for phase 2 if/when obsidian-writer supports them.
Listing supports:
status:todo(default),done,cancelled, oralllimit: optional positive integervault: optional vault override
Examples
Read today's inbox:
obsidian_read_inbox()Read a specific inbox day:
obsidian_read_inbox(date="2026-06-24")Create a task using the configured default vault:
obsidian_create_task(
title="Pay electricity bill",
due="2026-06-25",
priority="high",
tags=["home", "bills"],
source="assistant",
)List pending tasks:
obsidian_list_tasks(status="todo", limit=20)Create or append a note:
obsidian_create_or_append_note(
title="Project ideas",
content="- Try a simpler publishing flow",
)Local development
Run the server over stdio:
uv run --with fastmcp --with httpx python obsidian_writer_mcp.pyThe process will wait for MCP stdio messages; that is expected.
Available Tools
13 toolsobsidian_append_inboxA
Append one line to today's inbox file in the user's Obsidian vault. Use when the user asks to add/save/capture something to inbox.
Inputs: line (required), tags, timestamp. Returns: object
obsidian_append_noteA
Append Markdown content to an existing note in the configured default vault. Use when the user asks to add content to an existing note. Before using, prefer calling obsidian_list_notes to discover the correct slug. If needed, use obsidian_read_note to understand the note before adding content.
Inputs: slug (required), content (required). Returns: object
obsidian_create_noteA
Create a new standalone Markdown note in the configured default vault. Use when the user asks to create a new note. mode=create always creates a new note; if the same slug already exists, obsidian-writer creates _2, _3, etc. Content should be well-formatted Markdown. Do not repeat the title as a heading inside content when title is already provided separately.
Inputs: title (required), content (required). Returns: object
obsidian_create_or_append_noteA
Create a note or append to an existing compatible note in the configured default vault. Use for ambiguous requests like "put this in note X" or "save this in a note about X". If a compatible note exists, use its slug and append. If not, let obsidian-writer create the note. Before using, prefer calling obsidian_list_notes.
Inputs: title (required), content (required), slug. Returns: object
obsidian_create_taskA
Create a structured Obsidian Tasks-compatible task in a vault. Use when the user asks for a task, todo, manual reminder, or pending action. Pass semantic fields only; obsidian-writer formats the final Markdown line. Dependencies are accepted for future compatibility but are not sent yet.
Inputs: due, done, tags, start, +11 more. Returns: object
obsidian_list_addA
Add one or more unchecked items to an Obsidian list in the configured default vault. Use when the user asks to add items to a named list. Before using this tool, call obsidian_list_lists when there is doubt about the exact list name.
Inputs: items (required), list_name (required). Returns: object
obsidian_list_listsA
List existing Obsidian lists in the configured default vault. Use before adding/removing/updating list items when the user gives an approximate list name. Prefer an existing compatible list to avoid creating duplicates such as mercado, compras, or lista-de-compras.
Inputs: no named parameters. Returns: object
obsidian_list_notesA
List existing notes in the configured default vault. Use before creating or updating a note when the user mentions a note by an approximate name. Prefer an existing compatible note instead of creating a duplicate.
Inputs: no named parameters. Returns: object
obsidian_list_removeA
Remove one or more items from an Obsidian list in the configured default vault. Use when the user asks to remove items from a named list. Before using this tool, call obsidian_list_lists when there is doubt about the exact list name.
Inputs: items (required), list_name (required). Returns: object
obsidian_list_tasksA
List structured Obsidian Tasks-compatible tasks from a vault. Use when the user asks what tasks/todos/reminders are pending, completed, cancelled, or all. By default lists pending todo tasks from the configured default vault.
Inputs: limit, vault, status. Returns: object
obsidian_list_updateA
Update list items in an Obsidian list in the configured default vault. Use when the user asks to rename/change existing list items. Before using this tool, call obsidian_list_lists when there is doubt about the exact list name.
Inputs: list_name (required), new_items (required), old_items (required). Returns: object
obsidian_read_inboxA
Read inbox items for a specific day from the configured default vault. Use when the user asks what was captured/saved in the inbox today or on a specific date. Date must be YYYY-MM-DD; when omitted, obsidian-writer uses today.
Inputs: date, vault. Returns: object
obsidian_read_noteA
Read an existing note from the configured default vault. Use before appending to a note or answering about its content. Use the slug returned by obsidian_list_notes.
Inputs: slug (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Most tools target distinct resources and actions (list operations vs note operations vs tasks vs inbox). The only potential confusion is among create_note, append_note, and create_or_append_note, but descriptions clarify their intended use cases.
All tools use the obsidian_ prefix and snake_case. However, list operations use a noun-first pattern (list_add, list_remove) while others use verb-first (read_note, create_task), which is a minor structural inconsistency.
13 tools is well within the ideal range for a domain-specific server focused on notes, lists, tasks, and inbox. Each tool has a clear role and contributes to the overall functionality.
Core workflows are covered (create/read/append notes, list management, tasks, inbox). Gaps include no delete for notes, no update/complete for tasks, and no explicit list creation, but these can often be worked around.
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Nifty's MCP server — exposes tasks, projects, messages, and files as tools for AI agents.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server to interact with Obsidian via the Local REST API community plugin.134,547MIT
- AlicenseNot gradedqualityCmaintenanceProvides an MCP server that allows AI assistants to interact with Obsidian vaults, enabling reading/writing notes, managing metadata, searching content, and working with daily notes.37MIT
- AlicenseNot gradedqualityDmaintenanceMCP server providing tools to interact with Obsidian via the Local REST API community plugin.5MIT
- AlicenseNot gradedqualityDmaintenanceMCP server that provides read and write access to an Obsidian vault by interacting directly with markdown files on disk. Supports searching, listing, reading, creating, editing, and appending notes without requiring any Obsidian plugins.ISC