Skip to main content
Glama
obsidian-mcp-guard

obsidian-mcp-guard

by codeafix

obsidian-mcp-guard

PyPI version Python 3.11+ License: MIT Tests

An MCP server for agent-safe Obsidian vault access. Provides read/write file tools with lint validation to prevent agents from writing malformed Obsidian markdown.

Why this exists

Most Obsidian MCP servers give agents direct write access with no markdown validation. Those that route through the Obsidian REST API gain some input sanitisation, but none validate content against Obsidian's markdown rendering rules before writing. obsidian-mcp-guard fills this gap: all writes are validated against Obsidian's markdown rules before they touch the vault, and if the content would render incorrectly, the write is rejected with a structured error explaining exactly which rule was violated. Writes can also be constrained to a single configurable vault path, giving agents a designated space to create and manage content on behalf of the user while preventing accidental or runaway writes to other vaults on the same filesystem. Directory traversal attacks are blocked at the path resolution layer, so a misconfigured, misbehaving, or prompt-injected agent cannot escape the write vault by constructing paths like Claude/../OtherVault/note.md

Related MCP server: Cursidian

Features

  • Read/list/create/update/delete/move notes via HOST_VAULT_PATH on the host filesystem

  • Lint validation on all writes using mdlint-obsidian — blocks writes that violate Obsidian markdown rules (unclosed wikilinks, raw HTML, standard-markdown links, etc.)

  • Write-vault isolation — writes are constrained to a single configurable vault; directory-traversal attacks are blocked on both read and write paths

  • Composable — create_vault_server() returns a FastMCP instance that can be mounted into a larger server via import_server()

  • Pre-validation tool — lint_note lets agents check content before committing a write

Installation

pip install obsidian-mcp-guard

For Claude Desktop users who don't want a manual install, uvx runs it directly with no setup:

uvx obsidian-mcp-guard

For local development:

python -m venv .venv
source .venv/bin/activate
pip install -e .

Configuration

Environment variable

Default

Description

HOST_VAULT_PATH

(required)

Absolute path to the directory containing your vaults as subdirectories

WRITE_VAULT

Claude

Name of the only vault where write operations are permitted

Example layout expected under HOST_VAULT_PATH:

/path/to/your/vaults/
    Claude/      ← write operations land here
    Work/        ← readable but not writable
    Personal/    ← readable but not writable

Usage

As a standalone stdio server

# via the installed CLI entry point
HOST_VAULT_PATH=/path/to/your/vaults obsidian-mcp-guard

# or via python -m
HOST_VAULT_PATH=/path/to/your/vaults python -m obsidian_mcp_guard

Claude Desktop / Cursor config

{
  "mcpServers": {
    "obsidian": {
      "command": "uvx",
      "args": ["obsidian-mcp-guard"],
      "env": {
        "HOST_VAULT_PATH": "/path/to/your/vaults",
        "WRITE_VAULT": "Claude"
      }
    }
  }
}

Claude Code

claude mcp add obsidian -- uvx obsidian-mcp-guard

Pass environment variables with -e:

claude mcp add obsidian -e HOST_VAULT_PATH=/path/to/your/vaults -e WRITE_VAULT=Claude -- uvx obsidian-mcp-guard

Mounted into another FastMCP server

from contextlib import asynccontextmanager
from fastmcp import FastMCP
from obsidian_mcp_guard import create_vault_server

@asynccontextmanager
async def lifespan(app):
    await app.import_server(create_vault_server(
        vault_path="/path/to/your/vaults",
        write_vault="Claude"
    ))
    yield

mcp = FastMCP("my-agent", lifespan=lifespan)

@mcp.tool()
def search_notes(...):
    ...

Tools

Tool

Description

read_note(source)

Return full content of a note in vault/path.md format

list_notes(vault, folder?, recursive?)

List note paths within a vault or subfolder

create_note(source, content, overwrite?)

Create a note; blocked by lint errors

update_note(source, content, mode?)

Overwrite or append to a note; blocked by lint errors

delete_note(source)

Move a note to .trash/ (recoverable)

move_note(source_path, dest_path, create_dirs?)

Move a note within the write vault; rewrites wikilinks in all vault files

lint_note(content)

Pre-validate content without writing; returns {valid, errors, warnings}

Development

make install   # install package + test dependencies
make test      # run tests with coverage (90% minimum)
make build     # build source and wheel distributions
make clean     # remove build artefacts and cache files

See CONTRIBUTING.md for full guidelines.

  • mdlint-obsidian — the lint engine used to validate markdown against Obsidian's rendering rules

Available Tools

7 tools
create_noteA

Create a new note at source (vault/relative/path.md format). Refuses with a structured error if the target vault is not WRITE_VAULT. Refuses to overwrite an existing file unless overwrite=True. Creates intermediate directories as needed.

Inputs: source (required), content (required), overwrite. Returns: object

delete_noteA

Move a note to the .trash folder at the vault root rather than deleting it permanently. The directory structure within the vault is preserved under .trash so the file can be recovered if needed. Refuses with a structured error if the target vault is not WRITE_VAULT.

Inputs: source (required). Returns: object

lint_noteA

Pre-validate markdown content without writing it to disk. Returns {"valid": bool, "errors": [...], "warnings": [...]}. Use this to check content before calling create_note or update_note.

Inputs: content (required). Returns: object

list_notesA

List note paths within a vault, optionally scoped to a subfolder. Returns paths in vault/relative/path.md format — the same format as the source field from search_notes — so results can be passed directly to read_note. Set recursive=False to list only the immediate folder (non-recursive).

Inputs: vault (required), folder, recursive. Returns: result

move_noteA

Move a note from source_path to dest_path (vault/relative/path.md format). Both paths must be within WRITE_VAULT. Fails if dest_path already exists — there is no overwrite option. If create_dirs=True (default), creates missing parent directories. After a successful move, wikilinks in all vault .md files that referenced the old filename are rewritten to use the new filename. Returns {"success": bool, "source": str, "destination": str, "links_updated": int}.

Inputs: dest_path (required), source_path (required), create_dirs. Returns: object

read_noteA

Return the full markdown content of a note. source is in vault/relative/path.md format, as returned by search_notes. The full filesystem path is HOST_VAULT_PATH / source.

Inputs: source (required). Returns: result

update_noteA

Update an existing note. mode must be 'overwrite' (replace entire content) or 'append' (add content to the end of the file). Refuses with a structured error if the target vault is not WRITE_VAULT.

Inputs: source (required), content (required), mode. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.4/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool targets a distinct operation: create, read, update, delete, move, list, and lint. No two tools overlap in purpose, so an agent can clearly differentiate them.

    Naming Consistency5/5

    All tool names follow the verb_note/verb_notes pattern (delete_note, move_note, lint_note, read_note, list_notes, create_note, update_note), demonstrating a highly consistent naming convention.

    Tool Count5/5

    Seven tools is a well-scoped set for a note management server, covering the essential operations without unnecessary bloat or sparse coverage.

    Completeness4/5

    The set covers the full CRUD lifecycle plus move, list, and lint, but the descriptions reference a search_notes tool that is not exposed. This creates a potential dead end for agents that rely on that referenced capability.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables Cursor agents to read, write, search, and manage local Obsidian vaults via 13 tools with safe writes and direct filesystem access.
      4
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables LLM clients to read, create, edit, delete, move, and search notes in local Obsidian vaults via direct filesystem access, including tag management and support for multiple vaults.
      22 PyPI
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables agents to search, read, and write notes in an Obsidian vault, including creating and updating notes in an inbox and syncing changes with Gitea/GitHub.
      MIT