Obsidian CLI MCP Server

MCP server that exposes Obsidian vault operations over HTTP. Uses the obsidian CLI via subprocess — requires the Obsidian desktop app to be running.

Placeholders: Examples use <project-root>, <vault-root>, and localhost:3100 — replace with your actual paths and host/port. All examples are generic and safe for public use.

Prerequisites

• Obsidian desktop app installed and running
• gtimeout (GNU coreutils): brew install coreutils on macOS
• Python 3.10+

Quick Start

cd <project-root>   # e.g. ~/projects/obsidian-cli-mcp
pip install -r requirements.txt
cp .env.example .env   # edit .env with your vault path
python -m src.server

Server listens on http://localhost:3100/mcp.

Dev mode (auto-restart on file changes):

make dev

Smoke test (run all read operations; edit hardcoded paths in scripts/smoke_test.py to match your vault):

python scripts/smoke_test.py

Tools

Tool	Purpose
health	Check obsidian CLI and vault status
obsidian_base_query	Query .base database files
obsidian_base_views	List views in a .base file
obsidian_read	Read a note by name or path
obsidian_search	Full-text search with context
obsidian_search_json	Full-text search as JSON
obsidian_daily_read	Read today's daily note
obsidian_daily_append	Append to today's note (write-gated)
obsidian_files	List files in a folder
obsidian_backlinks	Notes that link to this note
obsidian_links	Outgoing links from a note
obsidian_tags	All tags with counts
obsidian_tags_file	Tags for a specific file
obsidian_properties	Frontmatter properties
obsidian_create	Create a note (write-gated)

Environment Variables

Variable	Default	Purpose
OBSIDIAN_VAULT_PATH	(in .env)	Vault directory (cwd for obsidian CLI); see .env.example
OBSIDIAN_VAULT	(none)	Vault name when multiple vaults exist
OBSIDIAN_TIMEOUT_SECONDS	10	Timeout for obsidian CLI (base queries use 30s)
ALLOW_WRITE_COMMANDS	false	Enable create, append, property:set
MCP_HOST	0.0.0.0	Bind address
MCP_PORT	3100	Server port
MCP_TRANSPORT	streamable-http	stdio for Cursor command; streamable-http for URL

Connect from Continue

Place config at <vault-root>/.continue/mcpServers/obsidian-cli-mcp.yaml:

name: Obsidian CLI
version: 1.0.0
schema: v1
mcpServers:
  - name: obsidian-cli-mcp
    type: streamable-http
    url: http://localhost:3100/mcp

Start the server before using Continue. Or use cn --mcp http://localhost:3100/mcp.

Connect from Cursor

Option A – Command (recommended) – Cursor spawns the server; no manual start needed:

{
  "mcpServers": {
    "obsidian-cli-mcp": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "<project-root>",
      "env": { "MCP_TRANSPORT": "stdio" }
    }
  }
}

Use your actual project path for cwd, or omit it if the project is your workspace root.

Option B – URL – Start the server manually first (python -m src.server), then add:

{
  "mcpServers": {
    "obsidian-cli-mcp": {
      "url": "http://localhost:3100/mcp"
    }
  }
}