obsidian-mcp is a self-hosted Model Context Protocol (MCP) server designed to provide AI agents with a persistent, shared, and human-auditable memory system. Its core storage is not an invisible vector database, but rather plain Markdown files in the user's Obsidian vault, supplemented by full-text search, semantic search, and a wikilink graph. Obsidian serves as the human viewing window: users can open notes, read what the agent has written, make corrections or deletions, and can also move the entire folder elsewhere.
Purpose
The server provides connected MCP clients with accessible storage, keyword and semantic search, and graph operations on Markdown notes. The agent autonomously decides what to read and write; the server itself does not run automatic extraction, consolidation, or decay pipelines—the agent remembers information by writing notes and forgets information by deleting notes.
Main Capabilities
The server exposes 25 MCP tools, divided into five categories:
Search and Discovery: keyword_search (full-text search based on PostgreSQL tsvector, supporting folder, tag, and frontmatter filtering), semantic_search (vector similarity search based on pgvector, returning one preview chunk per note), list_notes (sorted by modification time), get_recent (most recently changed), get_tags (tags and counts), get_vault_guide (provides an Obsidian getting-started guide and the vault's CLAUDE.md in real time).
Note Reading and Writing: read_note returns structured results (path, title, tags, frontmatter YAML and JSON views, headings, content, truncation information, etc.), supports reading a single section by section or continuing truncated reads via offset, limited by MAX_READ_RESPONSE_CHARS (default 40,000). create_note writes atomically and refuses to overwrite. edit_note supports four mutually exclusive modes: full replacement (default), append (append=True), find and replace (find=..., optional replace_all), section-based editing (section=<heading>, supporting ATX headings, Parent/Child path style, and #N ordinal disambiguation), dry_run=True returns a unified diff without writing. move_note moves a note and can optionally rewrite incoming wikilink references ([[Old]], [[Old|alias]], [[Old#anchor]], ![[Old]], [[folder/Old]]). delete_note by default soft-deletes to the .trash/ directory (with timestamp and hash, a single non-replacing rename, avoiding overwriting existing trash entries); with permanent=True it deletes permanently. set_frontmatter performs structured YAML changes, keeping the body byte-identical when only modifying frontmatter.
File Access (Non-Markdown): read_file, write_file, list_files, delete_file are used for raw reading, writing, and browsing of arbitrary vault files (PDFs, images, skill assets, data files). Pure byte transfer, with no server-side PDF/text extraction, and no embedding or indexing of non-Markdown files. read_file returns text for text-class files, returns inline image blocks for images, and returns base64 strings for other binaries; limited by MAX_FILE_READ_BYTES (default 10 MB) and MAX_READ_RESPONSE_CHARS, and can continue via offset. write_file by default does not overwrite, automatically creates parent directories, writes atomically, with an upper limit of MAX_FILE_WRITE_BYTES (default 25 MB). list_files provides ls-style browsing, supporting glob filtering and result limits. delete_file soft-deletes non-Markdown files to .trash/, refusing Markdown (delete_note should be used), directories, and symbolic links. All file tools reuse path traversal protection and exclude any path component starting with a dot (such as .obsidian, .git, .trash).
Edit Protection: When editing, updating frontmatter, moving or deleting notes, or overwriting or deleting raw files, the content_hash obtained at read time can be passed as expected_hash. The canonical token is sha256:<64 lowercase hexadecimal digits>, based on the completeCalculated over the raw file bytes. Expired tokens will reject the operation before the change and return an MCP-REFUSAL JSON line containing stale_precondition and the current hash. This parameter is optional by default, and WRITE_PRECONDITION_REQUIRED=true can enforce it. Create operations are exempt, and a provided token is rejected (no_incumbent). Files exceeding the read limit cannot be protected.
Transfer capability: Since MCP clients cannot directly pass the bytes of the file the user is viewing, the server provides short-lived capability links redeemed through public /transfer/* routes. request_upload generates a one-time link bound to a single target path; after the user opens it and selects a file, it is written to the specified path. check_upload reports pending/uploading/completed/unknown/revoked/expired status. request_download generates a download link.
Usage
The server is built on Python 3.12, FastAPI, PostgreSQL, and pgvector, with pluggable embedding models (Ollama bge-m3 or OpenAI text-embedding-3-small/large). It supports OAuth or bearer key authentication and can run in multi-user mode. After an agent connects via the MCP protocol, it can autonomously call the above tools to read and write. The library is self-describing: on the first call, the agent can read the library guide to learn the folder layout, frontmatter patterns, and tag conventions, without needing to re-explain them each session.
Use cases
Suitable for users who want to provide persistent, auditable memory for AI agents, especially those already using Obsidian to manage notes. Typical scenarios include: home lab configuration management (the agent finds and modifies configurations while updating documentation), cross-session project note updates (such as generating Obsidian session logs from Claude Code sessions), and accessing the same library when conversing with the agent on mobile (protected via OAuth, accessible from a browser, phone, n8n workflow, or any notebook).
Limitations
The server does not provide automatic extraction, consolidation, or decay pipelines; memory depends entirely on the agent actively writing and deleting. Non-Markdown files are only transferred as bytes, withouttext extraction, embedding, or indexing. File reads and writes have size limits (default read 10 MB, write 25 MB), and note read responses have a character limit (default 40,000). Path traversal protection excludes all path components starting with a dot. Files exceeding the read limit cannot use hash protection. For specific installation commands, configuration details, and complete API parameters, please refer to the project repository.
