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"
    }
  }
}