obsidian-codex-mcp
You can use this server as a local-first MCP interface to read, search, create, update, and manage an Obsidian vault and its Bases directly on disk.
Configure the Obsidian vault path.
Read, create, update, and delete markdown notes.
List and search notes by content, title, or tags, optionally within a folder.
Retrieve all tags, backlinks, and wikilinks from notes.
Create folders and inspect the vault folder structure.
Create, read, update, list, and delete Obsidian
.basefiles with schema validation.Support table, list, cards, and map Bases views, including map marker/zoom round-tripping.
Enforce safety features such as read-only mode, backup-on-write, vault path isolation, and path traversal protection.
Provides tools to interact with an Obsidian vault by reading and writing markdown files directly on disk, including note management, search, tags, backlinks, and folder operations.
Kika Obsidian MCP
Local-first MCP server for working with an Obsidian vault.
No Obsidian plugin required
No API key required
No cloud service required
No Obsidian running in the background
This is for people who want MCP clients to work directly with markdown files on disk.
Independent open-source project. Not affiliated with Obsidian, Anthropic, OpenAI, or any MCP client.
What it does
It lets MCP clients work with your vault to:
read and search notes
create and update notes
create and edit Obsidian Bases (
.basefiles) with schema validationgenerate summaries, status reports, and release notes
automate local knowledge workflows
All directly against your local markdown files.
Related MCP server: kObsidian MCP
Best for
Anyone using an MCP client — Claude Code, Claude Desktop, Cursor, Cline, Codex, Grok — who wants safe local access to an Obsidian vault
Developers who prefer filesystem-based Obsidian automation over the Local REST API plugin
People who want to create and edit Obsidian Bases (
.base) from an agentPersonal knowledge bases, project logs, daily notes, task notes, and markdown-first workflows
Why this exists
There are already a handful of Obsidian MCP servers. Many depend on the Obsidian Local REST API plugin or run as an Obsidian plugin. This project is intentionally simpler:
direct filesystem access to a local vault
no network calls
no Obsidian API token
works with any MCP client — simple JSON or TOML config for Claude Code, Claude Desktop, Cursor, Cline, Codex, and Grok
tolerant of real-world vaults with imperfect frontmatter
path traversal protection so tools cannot escape the configured vault
optional read-only mode for safer review/search workflows
optional backup-on-write before updates and deletes
first-class Obsidian Bases (
.base) support with schema validation — a differentiator: almost no other Obsidian MCP server can create or edit Bases, and this one validates them against the official schema so it never writes a file Obsidian would silently reject
How it compares
Need | This project |
Use Obsidian with any MCP client | Yes — Claude Code, Claude Desktop, Cursor, Cline, Codex, Grok |
Config format | JSON or TOML, per client (examples for each) |
Require an Obsidian plugin | No |
Require an API key | No |
Require Obsidian to be open | No |
Read/write markdown files directly | Yes |
Create and edit Obsidian Bases ( | Yes, with schema validation |
Work over a remote HTTP API | No, local stdio MCP only |
Safety features
Designed to be useful without being reckless:
read-only mode, which refuses writes
backup-on-write mode before updates and deletes
vault path isolation
path traversal protection
no external network calls
Tools
configure_vault- set or change the vault pathget_note- read one markdown note by vault-relative pathcreate_note- create a new markdown note with optional metadataupdate_note- update note content and/or frontmatterdelete_note- delete a markdown notelist_notes- list notes in the vault or a foldersearch_notes- search note title, content, and tagsget_all_tags- list unique tags from frontmatter and inline tagsget_backlinks- find notes that link to a noteget_note_links- extract wikilinks from a notecreate_folder- create a folder inside the vaultget_folder_structure- return the vault folder tree
Bases (.base files)
First-class, schema-validated support for Obsidian Bases — database-like views over your notes. Very few Obsidian MCP servers support these.

create_base- create a.basefile, validated against the Bases schema before writingupdate_base- merge changes into a base (update a view by name, add/remove views, change filters/formulas/properties)get_base- read a.baseas parsed structure + raw YAML; tolerant of imperfect fileslist_bases- list.basefiles in the vault or a folder, with their view namesdelete_base- delete a.basefile

All four Obsidian view modes are supported — table, list, cards, and map — and any of them can be mixed in a single base. Map views (from the Maps community plugin) round-trip cleanly too: their marker and zoom settings are preserved on read and re-write.
See docs/bases-examples.md for copyable examples of each view mode.
Demo

Full-length clip: Obsidian + MCP demo
Quick start
Install
Requirements:
Python 3.10 or newer recommended
An Obsidian vault stored as local markdown files
git clone https://github.com/aka-kika/kika-obsidian-mcp.git
cd kika-obsidian-mcp
./install.sh /absolute/path/to/your/obsidian-vaultinstall.sh creates a local virtualenv, installs dependencies, verifies against your vault, then prints ready-to-paste config for the client you choose (--client claude|claude-desktop|codex|cursor|cline|grok, default: all).
Prefer to do it by hand? The manual steps are:
python3 -m venv .venv
.venv/bin/python -m pip install --upgrade pip
.venv/bin/python -m pip install -r requirements.txt
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python test_server.pyConfigure your MCP client
The server is a local stdio MCP server, so any MCP-capable client can run it. Point the client at your virtualenv's Python and server.py, and set the vault path via env. Then restart or reconnect the client.
Claude Code
claude mcp add kika-obsidian \
--env OBSIDIAN_VAULT_PATH="/absolute/path/to/your/obsidian-vault" \
--env OBSIDIAN_READ_ONLY="false" \
--env OBSIDIAN_BACKUP_ON_WRITE="true" \
-- /absolute/path/to/kika-obsidian-mcp/.venv/bin/python \
/absolute/path/to/kika-obsidian-mcp/server.pyClaude Desktop / Cursor / Cline
Add this to the client's MCP config (claude_desktop_config.json, or the equivalent mcpServers block):
{
"mcpServers": {
"kika-obsidian": {
"command": "/absolute/path/to/kika-obsidian-mcp/.venv/bin/python",
"args": ["/absolute/path/to/kika-obsidian-mcp/server.py"],
"env": {
"OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/obsidian-vault",
"OBSIDIAN_READ_ONLY": "false",
"OBSIDIAN_BACKUP_ON_WRITE": "true"
}
}
}
}Codex / Grok
Add this to ~/.codex/config.toml (or ~/.grok/config.toml):
[mcp_servers.kika-obsidian]
command = "/absolute/path/to/kika-obsidian-mcp/.venv/bin/python"
args = ["/absolute/path/to/kika-obsidian-mcp/server.py"]
enabled = true
[mcp_servers.kika-obsidian.env]
OBSIDIAN_VAULT_PATH = "/absolute/path/to/your/obsidian-vault"
OBSIDIAN_READ_ONLY = "false"
OBSIDIAN_BACKUP_ON_WRITE = "true"For a safer read/search-only setup, set OBSIDIAN_READ_ONLY="true" (TOML: OBSIDIAN_READ_ONLY = "true").
Environment
Variable | Required | Default | Description |
| yes | none | Absolute path to the vault folder. |
| no |
| When true, create/update/delete/folder creation tools refuse writes. |
| no |
| When true, copies existing notes into |
Safety model
All note paths are resolved relative to
OBSIDIAN_VAULT_PATH.Absolute paths and
../path traversal are rejected.Writes can be disabled with
OBSIDIAN_READ_ONLY=true(this also blockscreate_base,update_base, anddelete_base).Existing notes and
.basefiles can be copied to.obsidian-mcp-backups/before update/delete withOBSIDIAN_BACKUP_ON_WRITE=true.Deletes are extension-scoped:
delete_noteonly removes markdown (.md) notes anddelete_baseonly removes Bases (.base) files. Neither can touch other file types.Base tools accept only
.basepaths and note tools only.mdpaths, so the two never cross-contaminate.The server makes no external network calls.
Broken YAML frontmatter does not break listing/search; the note is still readable with empty metadata.
Development
Run the local test script:
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python test_server.pyStart the MCP server:
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python server.pyOptional automation
Generate a daily project status report from your vault:
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python scripts/daily_status_report.py --folder "Projects"Write the report back into Obsidian:
OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python scripts/daily_status_report.py \
--folder "Projects" \
--write "Reports/Daily Project Status.md"The script reports recent notes, markdown checkbox tasks, and top tags. It uses backup-on-write when updating an existing report note.
Common workflows
See docs/common-workflows.md for practical examples:
safe vault exploration
project catch-up
daily status reports
release notes after shipping
vault triage
index note creation
finding underlinked notes
safe editing checklist
Templates
Copyable Obsidian note templates live in docs/templates:
Work log for daily project status and workstream summaries
Project session log for per-project session notes, decisions, links, and next moves
Weekly review for accomplishments, open loops, and next-week priorities
Optional skill
This repo includes lightweight agent workflow skills:
skills/obsidian-vault-workflow/SKILL.md
skills/release-note-captain/SKILL.mdUse them as guidance for agents that work with this MCP server. They cover safe vault exploration, editing discipline, daily status reports, vault triage, project catch-up prompts, and release-note capture after a project ships.
FAQ
Is this an Obsidian MCP server?
Yes. It is a local MCP server for Obsidian vaults. It exposes tools for notes, tags, backlinks, wikilinks, folders, search, and optional writes.
Which MCP clients does it work with?
Any client that can run a local stdio MCP server — Claude Code, Claude Desktop, Cursor, Cline, Codex, and Grok are all covered with copy-paste config above. It is just a local Python process, so anything that speaks MCP over stdio can use it. Run ./install.sh --client <name> /path/to/vault to print the exact config for your client.
Does it support Obsidian Bases?
Yes, with dedicated schema-validated tools. create_base, update_base, get_base, list_bases, and delete_base let MCP clients build and edit .base files directly on disk. Every write is validated against the official Bases schema first, so it never writes a file Obsidian would silently reject, and errors name the exact offending path (for example, views[0].groupBy missing 'property' key). get_base is tolerant of imperfect files: if the YAML cannot be parsed it returns the raw content with a parse_error flag instead of failing. All four view modes — table, list, cards, and map — are supported, and map bases from the Maps community plugin round-trip without losing their marker/zoom settings. This is a differentiator — almost no other Obsidian MCP server can create or edit Bases. See docs/bases-examples.md.
Does it need the Obsidian Local REST API plugin?
No. It reads and writes markdown files directly from the vault folder.
Does Obsidian need to be running?
No. Because this server works on local files, Obsidian does not need to be open.
Can I make it read-only?
Yes. Set OBSIDIAN_READ_ONLY=true to allow search and inspection while refusing create, update, delete, and folder creation tools.
Current limitations
Search is simple substring search, not semantic or indexed search.
No Obsidian command palette or plugin API access.
No conflict resolution for simultaneous edits.
No template expansion.
No sync-provider awareness.
License
MIT
Available Tools
17 toolsconfigure_vaultA
Configure the Obsidian vault path.
Args: vault_path: Absolute path to your Obsidian vault
Inputs: vault_path (required).
create_baseA
Create a new Obsidian Base (.base) file with schema validation.
Bases are database-like views over your notes. The structure is validated against the official Bases schema before anything is written; an invalid base is rejected with a message naming the offending path, and no file is created.
Args: path: Vault-relative path ending in .base (e.g., "Bases/Tasks.base") views: List of view objects (at least one). Each needs a "type" (table | list | cards | map) and usually a "name" and "order". filters: Optional global filter. Either a string statement or a mapping with one of "and" / "or" / "not" holding a list of conditions. formulas: Optional mapping of formula name -> expression string. properties: Optional mapping of property name -> config (e.g., {"status": {"displayName": "Status"}}). summaries: Optional mapping of summary name -> expression string.
Inputs: path (required), views (required), filters, formulas, +2 more.
create_folderA
Create a new folder in the vault.
Args: folder_path: Path to the new folder (e.g., "projects/new-project/")
Inputs: folder_path (required).
create_noteA
Create a new note.
Args: path: Path for the new note (e.g., "notes/new-note.md") content: Note content in Markdown title: Optional title (defaults to filename) tags: Optional list of tags
Inputs: path (required), content (required), tags, title.
delete_baseA
Delete a .base file.
Respects read-only mode and backup-on-write. Only .base files can be deleted through this tool.
Args: path: Vault-relative path to the .base file to delete.
Inputs: path (required).
delete_noteB
Delete a note permanently.
Args: path: Path to the note to delete
Inputs: path (required).
get_all_tagsA
Get all unique tags used in the vault.
Inputs: no named parameters.
get_backlinksA
Find all notes that link to the specified note.
Args: path: Path to the target note
Inputs: path (required).
get_baseA
Read a .base file as a parsed structure plus its raw YAML.
Tolerant of imperfect files: if the YAML cannot be parsed, the raw content is returned with a "parse_error" field instead of failing.
Args: path: Vault-relative path to the .base file.
Inputs: path (required).
get_folder_structureA
Get the complete folder structure of the vault.
Inputs: no named parameters.
get_noteA
Get a note by its path.
Args: path: Path to the note relative to vault root (e.g., "notes/my-note.md")
Inputs: path (required).
get_note_linksB
Get all wikilinks from a note.
Args: path: Path to the note
Inputs: path (required).
list_basesA
List all .base files in the vault or a folder, with their view names.
Args: folder: Optional folder path to search within (e.g., "Bases/").
Inputs: folder.
list_notesA
List all notes in the vault or a specific folder.
Args: folder: Optional folder path (e.g., "notes/" or "projects/")
Inputs: folder.
search_notesA
Search notes by content, title, or tags.
Args: query: Search query string folder: Optional folder to search within
Inputs: query (required), folder.
update_baseA
Update an existing .base file with merge semantics, then re-validate.
The file is read, the requested changes are merged, the whole structure is re-validated, the original is backed up (when backup-on-write is enabled), and the result is written back.
Args: path: Vault-relative path to the .base file. filters: When provided, replaces the global filters wholesale. To remove filters entirely, pass replace_filters=true and leave this unset. formulas: Mapping merged into existing formulas. A null value for a key removes that formula. properties: Mapping merged into existing properties (null removes). summaries: Mapping merged into existing summaries (null removes). upsert_views: List of view objects. Each replaces the existing view with the same "name", or is appended when there is no match. remove_views: List of view names to delete. replace_filters: Set true (with filters unset) to remove global filters.
Inputs: path (required), filters, formulas, summaries, +4 more.
update_noteC
Update an existing note.
Args: path: Path to the note content: New content (optional) metadata: Metadata updates (optional)
Inputs: path (required), content, metadata.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool targets a distinct action or resource: configuration, note/base/folder CRUD, search, tags, links, and folder structure. There is no overlapping functionality; even similar tools like list_notes and search_notes serve clear different purposes.
All tool names follow a consistent `verb_noun` pattern in snake_case, e.g., `create_note`, `delete_base`, `get_all_tags`. No mixing of conventions or vague verbs.
17 tools is well-scoped for a vault management server. Each tool addresses a specific operation without unnecessary redundancy, covering notes, bases, folders, search, and metadata.
Core operations are covered: CRUD for notes and bases, search, tags, links, folder listing, and configuration. Minor gaps exist, such as no dedicated tool for folder deletion or note moving, but these are not essential for basic workflows.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
MCP server for OpenAI API (chat completions, image generation, embeddings) via AceDataCloud
An MCP server that gives your AI access to the source code and docs of all public github repos
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Related MCP Servers
- AlicenseAqualityDmaintenanceMCP server to interact with Obsidian via the Local REST API community plugin.134,535MIT
- AlicenseAqualityBmaintenanceFilesystem first MCP server for Obsidian vaults with an LLM-Wiki layer on top.66101 npm8Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to read and search your Obsidian vault through a local MCP server, keeping everything private and local.Apache 2.0
- AlicenseNot gradedqualityDmaintenanceRemote MCP server that gives AI agents read/write access to your Obsidian vaults, supporting both local desktop vaults and headless mode.3,713 npmMIT