Skip to main content
Glama
obsidian-writer-mcp

obsidian-writer-mcp

by ariedotme

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:

  1. .env next to obsidian_writer_mcp.py

  2. .env in the current working directory

Create a local .env from the example:

cp .env.example .env

Variables:

  • 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 receive vault. Default: default.

Example:

OBSIDIAN_WRITER_BASE_URL=http://obsidian-writer:3000
OBSIDIAN_DEFAULT_VAULT=my-vault

The .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-writer

If 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. The date argument is optional; when omitted, obsidian-writer uses 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:

  • vault

  • title

  • content (legacy fallback for title)

  • status: todo, done, cancelled

  • due, scheduled, start, done, cancelled: dates as YYYY-MM-DD

  • priority: highest, high, medium, low, lowest, none

  • recurrence

  • tags

  • source

  • due_text (legacy; ignored when due is 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, or all

  • limit: optional positive integer

  • vault: 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.py

The process will wait for MCP stdio messages; that is expected.

Available Tools

13 tools
obsidian_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

    A3.9/5.0

    Scored across 13 tools

    Disambiguation4/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness3/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      Provides 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.
      37
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server providing tools to interact with Obsidian via the Local REST API community plugin.
      5
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP 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