obsidian-mcp-guard
Provides read/write file tools for Obsidian vaults with lint validation to prevent malformed markdown, including creating, updating, deleting, moving notes, and listing notes within configured vaults.
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-mcp-guard Create a note in Claude vault titled 'Meeting Notes' with content about today's agenda."
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-mcp-guard
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_PATHon the host filesystemLint 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 aFastMCPinstance that can be mounted into a larger server viaimport_server()Pre-validation tool —
lint_notelets agents check content before committing a write
Installation
pip install obsidian-mcp-guardFor Claude Desktop users who don't want a manual install, uvx runs it directly with no setup:
uvx obsidian-mcp-guardFor local development:
python -m venv .venv
source .venv/bin/activate
pip install -e .Configuration
Environment variable | Default | Description |
| (required) | Absolute path to the directory containing your vaults as subdirectories |
|
| 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 writableUsage
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_guardClaude 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-guardPass environment variables with -e:
claude mcp add obsidian -e HOST_VAULT_PATH=/path/to/your/vaults -e WRITE_VAULT=Claude -- uvx obsidian-mcp-guardMounted 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 |
| Return full content of a note in |
| List note paths within a vault or subfolder |
| Create a note; blocked by lint errors |
| Overwrite or append to a note; blocked by lint errors |
| Move a note to |
| Move a note within the write vault; rewrites wikilinks in all vault files |
| Pre-validate content without writing; returns |
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 filesSee CONTRIBUTING.md for full guidelines.
Related projects
mdlint-obsidian — the lint engine used to validate markdown against Obsidian's rendering rules
Available Tools
7 toolscreate_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
Scored across 7 tools
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.
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.
Seven tools is a well-scoped set for a note management server, covering the essential operations without unnecessary bloat or sparse coverage.
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
Related MCP Connectors
Research-backed lint + generation for agent context files (CLAUDE.md, AGENTS.md) + prompt enhancer.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Safe folder access for ChatGPT and Claude: read, write and search files, risky tools opt-in.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides AI agents with Obsidian vault operations via the official CLI, including reading, writing, searching notes, and managing files, with security and concurrency protections.7MIT
- AlicenseAqualityBmaintenanceEnables Cursor agents to read, write, search, and manage local Obsidian vaults via 13 tools with safe writes and direct filesystem access.4MIT
- AlicenseNot gradedqualityCmaintenanceEnables 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 PyPIMIT
- AlicenseNot gradedqualityCmaintenanceEnables 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