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 (.base files) with schema validation
• generate summaries, status reports, and release notes
• automate local knowledge workflows

All directly against your local markdown files.

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 agent
• Personal 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

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 path
• get_note - read one markdown note by vault-relative path
• create_note - create a new markdown note with optional metadata
• update_note - update note content and/or frontmatter
• delete_note - delete a markdown note
• list_notes - list notes in the vault or a folder
• search_notes - search note title, content, and tags
• get_all_tags - list unique tags from frontmatter and inline tags
• get_backlinks - find notes that link to a note
• get_note_links - extract wikilinks from a note
• create_folder - create a folder inside the vault
• get_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 .base file, validated against the Bases schema before writing
• update_base - merge changes into a base (update a view by name, add/remove views, change filters/formulas/properties)
• get_base - read a .base as parsed structure + raw YAML; tolerant of imperfect files
• list_bases - list .base files in the vault or a folder, with their view names
• delete_base - delete a .base file

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-vault

install.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.py

Configure 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.py

Claude 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

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 blocks create_base, update_base, and delete_base).
• Existing notes and .base files can be copied to .obsidian-mcp-backups/ before update/delete with OBSIDIAN_BACKUP_ON_WRITE=true.
• Deletes are extension-scoped: delete_note only removes markdown (.md) notes and delete_base only removes Bases (.base) files. Neither can touch other file types.
• Base tools accept only .base paths and note tools only .md paths, 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.py

Start the MCP server:

OBSIDIAN_VAULT_PATH="/absolute/path/to/your/vault" .venv/bin/python server.py

Optional 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: