Purpose
obsidian-codex-mcp is a local-first MCP server used to let MCP clients directly operate Markdown files in an Obsidian vault. It does not depend on Obsidian plugins, API keys, or cloud services, nor does it require the Obsidian application to be running in the background; all operations act directly on the local file system.
Main Capabilities
- Note operations: read a single note (get_note), create a note (create_note), update content or frontmatter (update_note), delete a note (delete_note), list notes (list_notes), search titles/content/tags (search_notes).
- Metadata and links: get all tags (get_all_tags), find backlinks (get_backlinks), extract wikilinks (get_note_links).
- Folder management: create a folder (create_folder), get the folder tree (get_folder_structure), configure the vault path (configure_vault).
- Bases support: create (create_base), update (update_base), read (get_base), list (list_bases), delete (delete_base) .base files; all writes are validated according to the official Bases schema, support the four view types table, list, cards, and map, and the marker/zoom settings of the Maps community plugin are preserved during read-write round trips.
- Automation scripts: can generate a daily project status report and write it back to Obsidian; the report includes recent notes, Markdown checkbox tasks, and popular tags.
Usage
Environment requirements: Python 3.10 or higher; the Obsidian vault stores Markdown files locally. Installation: running install.sh will create a local virtual environment, install dependencies, validate the vault, and output ready-to-use configuration for the corresponding client (--client claude|claude-desktop|codex|cursor|cline|grok, default all). Manual steps include: configure MCP client, point the client to the virtual environment's Python and server.py, set the vault path through environment variables, then restart or reconnect the client. Configuration examples: Claude Desktop / Cursor / Cline use an mcpServers configuration block; Codex / Grok use ~/.codex/config.toml or ~/.grok/config.toml. Security options: OBSIDIAN_READ_ONLY=true enables read-only mode (also blocks create_base, update_base, delete_base); OBSIDIAN_BACKUP_ON_WRITE=true copies existing notes and .base files to .obsidian-mcp-backups/ before updating/deleting. Path rules: all note paths are resolved relative to OBSIDIAN_VAULT_PATH; absolute paths and ../ path traversal are rejected; delete_note deletes only .md, delete_base deletes only .base; the two types of tool paths do not cross; the server does not make external network calls; corrupted frontmatter YAML does not affect listing/search, and notes remain readable but with empty metadata.
Applicable Scenarios
- Users who use MCP clients and want secure local access to an Obsidian vault.
- Developers who prefer file-system-based Obsidian automation rather than the Local REST API plugin.
- Users who want to create and edit Obsidian Bases (.base) through an agent.
- Personal knowledge bases, project logs, daily notes, task notes, and Markdown-first workflows.
Limitations
- Search is simple substring search, not semantic or indexed search.
- Cannot access the Obsidian command palette or plugin API.
- Does not handle conflict resolution for simultaneous editing.
- Does not support template expansion.
- Does not have sync-service awareness.
