mcp-obsidian-cli 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matt Stone
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,94 @@
+# mcp-obsidian-cli
+
+> **Trademark Notice:** "Obsidian" is a trademark of Obsidian Publishing, Inc. This project is not affiliated with or endorsed by Obsidian Publishing.
+
+MCP server that wraps the Obsidian CLI, giving AI assistants full access to Obsidian's native API — search index, wikilink resolution, tasks, properties, daily notes, backlinks, and 80+ commands — through the Model Context Protocol.
+
+## Why this exists
+
+Every existing Obsidian MCP server takes one of two approaches: the Local REST API plugin (requires API keys, HTTP overhead, limited command surface) or raw filesystem access (no Obsidian awareness — no search index, no wikilink resolution, no task queries). Both miss the point.
+
+`mcp-obsidian-cli` wraps the Obsidian CLI plugin, which talks directly to the running Obsidian instance via IPC. This means full access to Obsidian's internal APIs with zero configuration — no API keys, no REST plugins, no token management.
+
+## Quick start
+
+```bash
+npx mcp-obsidian-cli
+```
+
+## Claude Desktop config
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "obsidian": {
+      "command": "npx",
+      "args": ["-y", "mcp-obsidian-cli"],
+      "env": {
+        "OBSIDIAN_VAULT": "my-vault"
+      }
+    }
+  }
+}
+```
+
+## Requirements
+
+- Obsidian running with the CLI plugin active
+- `obsidian` on your PATH
+- Node.js >= 18
+
+## How it works
+
+The server exposes Obsidian CLI commands as MCP tools. A generic pass-through tool handles the full CLI surface (80+ commands), plus typed convenience tools for common operations:
+
+| Tool | Description |
+|------|-------------|
+| `obsidian` | Generic pass-through — run any CLI command |
+| `obsidian_daily_read` | Read today's daily note |
+| `obsidian_daily_append` | Append to daily note |
+| `obsidian_read` | Read a note by name or path |
+| `obsidian_search` | Full-text search with context |
+| `obsidian_tags` | List tags with counts |
+| `obsidian_tasks` | Query tasks (daily, todo, done) |
+| `obsidian_properties` | Read frontmatter properties |
+| `obsidian_create` | Create a new note |
+| `obsidian_property_set` | Set a frontmatter property |
+| `obsidian_backlinks` | List backlinks to a note |
+| `obsidian_files` | List vault files |
+| `obsidian_recents` | Recently opened files |
+
+The generic `obsidian` tool means the MCP server never falls behind the CLI — new CLI commands work immediately without a server update.
+
+## Environment variables
+
+| Variable | Default | Description |
+|---|---|---|
+| `OBSIDIAN_VAULT` | _(none)_ | Target vault by name |
+| `OBSIDIAN_CLI_PATH` | `obsidian` | Path to CLI binary |
+| `OBSIDIAN_TIMEOUT_MS` | `15000` | Command timeout |
+
+## Compared to alternatives
+
+| | mcp-obsidian-cli | REST API servers | Filesystem servers |
+|---|---|---|---|
+| Search index | Yes | Yes | No |
+| Wikilink resolution | Yes | Partial | No |
+| Task queries | Yes | No | No |
+| Property types | Yes | Partial | No |
+| Daily notes | Yes | No | No |
+| Backlinks | Yes | Yes | No |
+| API keys | None | Required | None |
+| Obsidian plugins | CLI plugin | REST API plugin | None |
+| Commands | 80+ | ~10 | ~6 |
+
+## License
+
+MIT
+
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Z8Z41G13PX)
+
+Maintained by [@stonematt](https://github.com/stonematt)
+Licensed under the MIT License

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "mcp-obsidian-cli",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "MCP server wrapping the Obsidian CLI — full native API access over Model Context Protocol",
+  "main": "server.js",
+  "bin": {
+    "mcp-obsidian-cli": "server.js"
+  },
+  "scripts": {
+    "start": "node server.js",
+    "test": "node --test test/run.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "mcp",
+    "obsidian",
+    "model-context-protocol",
+    "cli",
+    "claude",
+    "ai",
+    "knowledge-management"
+  ],
+  "author": "stonematt",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/stonematt/mcp-obsidian-cli.git"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "js-yaml": "^4.1.0",
+    "zod": "^3.25.0"
+  }
+}

package/server.js

@@ -0,0 +1,397 @@
+#!/usr/bin/env node
+/**
+ * obsidian-mcp — MCP server wrapping the Obsidian CLI.
+ *
+ * Exposes a single generic `obsidian` tool that passes any command string
+ * directly to the CLI, plus a handful of convenience tools for the most
+ * common operations (read, search, daily, tasks, properties, etc.).
+ *
+ * Environment variables:
+ *   OBSIDIAN_CLI_PATH    - Path to the obsidian CLI binary (default: "obsidian")
+ *   OBSIDIAN_VAULT       - Vault name to use (default: "")
+ *   OBSIDIAN_TIMEOUT_MS  - Command timeout in ms (default: 15000)
+ *
+ * Requirements:
+ *   - Obsidian must be running with the CLI plugin active.
+ *   - The `obsidian` binary must be on PATH (or set OBSIDIAN_CLI_PATH).
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { readFileSync, mkdirSync, existsSync } from "node:fs";
+import { load as yamlLoad } from "js-yaml";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { exec } from "node:child_process";
+
+const execFileAsync = promisify(execFile);
+const execAsync = promisify(exec);
+
+const CONFIG_DIR = join(homedir(), ".config", "mcp-obsidian-cli");
+const CONFIG_FILE = join(CONFIG_DIR, "config.yaml");
+
+function loadConfig() {
+  const defaults = { vault: "", cliPath: "obsidian", timeoutMs: 15000 };
+  let config = { ...defaults };
+
+  if (existsSync(CONFIG_FILE)) {
+    try {
+      const content = readFileSync(CONFIG_FILE, "utf8");
+      const fileConfig = yamlLoad(content);
+      if (fileConfig) {
+        if (fileConfig.vault) config.vault = fileConfig.vault;
+        if (fileConfig.cliPath) config.cliPath = fileConfig.cliPath;
+        if (fileConfig.timeoutMs) config.timeoutMs = fileConfig.timeoutMs;
+      }
+    } catch (err) {
+      console.error("Warning: failed to load config file:", err.message);
+    }
+  }
+
+  if (process.env.OBSIDIAN_VAULT) config.vault = process.env.OBSIDIAN_VAULT;
+  if (process.env.OBSIDIAN_CLI_PATH) config.cliPath = process.env.OBSIDIAN_CLI_PATH;
+  if (process.env.OBSIDIAN_TIMEOUT_MS) config.timeoutMs = parseInt(process.env.OBSIDIAN_TIMEOUT_MS, 10);
+
+  return config;
+}
+
+const config = loadConfig();
+const CLI = config.cliPath;
+const VAULT = config.vault;
+const TIMEOUT_MS = config.timeoutMs;
+
+async function checkObsidianRunning() {
+  try {
+    const { stdout: psOut } = await execAsync("ps aux | grep -i obsidian | grep -v grep | grep -v Helper", { timeout: 2000 });
+    const obsidianRunning = psOut.includes("/Applications/Obsidian.app");
+    if (!obsidianRunning) {
+      return { running: false, version: null };
+    }
+    const { stdout } = await execFileAsync(CLI, ["version"], { timeout: 2000 });
+    const hasStartupMsg = stdout.includes("Loaded updated app package") || 
+                          stdout.includes("Checking for update") ||
+                          stdout.includes("App is up to date") ||
+                          stdout.includes("Latest version is");
+    if (hasStartupMsg) {
+      return { running: false, version: null };
+    }
+    if (stdout.includes("(installer")) {
+      const match = stdout.match(/(\d+\.\d+\.\d+)/);
+      if (match) {
+        return { running: true, version: match[1] };
+      }
+    }
+    return { running: false, version: null };
+  } catch (err) {
+    return { running: false, version: null };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the Obsidian CLI with the given argument string.
+ * Returns { stdout, stderr } or throws on non-zero exit / timeout.
+ */
+async function run(argString) {
+  const args = parseArgs(argString);
+  if (VAULT) args.push(`vault=${VAULT}`);
+
+  try {
+    const { stdout, stderr } = await execFileAsync(CLI, args, {
+      timeout: TIMEOUT_MS,
+      maxBuffer: 4 * 1024 * 1024,
+      env: { ...process.env },
+    });
+    return { stdout: stdout.trimEnd(), stderr: stderr.trimEnd(), error: null };
+  } catch (err) {
+    if (err.code === 'ENOENT') {
+      return {
+        stdout: '',
+        stderr: '',
+        error: {
+          type: 'CLI_NOT_FOUND',
+          message: `Obsidian CLI not found at: ${CLI}. Set OBSIDIAN_CLI_PATH or ensure 'obsidian' is on PATH.`
+        }
+      };
+    }
+    if (err.killed) {
+      return {
+        stdout: '',
+        stderr: '',
+        error: {
+          type: 'TIMEOUT',
+          message: `Command timed out after ${TIMEOUT_MS}ms. Set OBSIDIAN_TIMEOUT_MS to increase timeout.`
+        }
+      };
+    }
+    const msg = err.stderr?.trimEnd() || err.message;
+    return { stdout: '', stderr: '', error: { type: 'EXECUTION_ERROR', message: msg } };
+  }
+}
+
+/**
+ * Minimal arg parser: splits on whitespace but respects key="value with spaces".
+ */
+function parseArgs(str) {
+  const args = [];
+  const re = /(?:[^\s"]+|"[^"]*")+/g;
+  let m;
+  while ((m = re.exec(str)) !== null) {
+    args.push(m[0]);
+  }
+  return args;
+}
+
+/** Standard MCP text result. */
+function text(content) {
+  return { content: [{ type: "text", text: content }] };
+}
+
+/** Standard MCP error result. */
+function errorResult(content, code = "EXECUTION_ERROR") {
+  return {
+    content: [{ type: "text", text: content }],
+    isError: true,
+  };
+}
+
+/** Run CLI, return MCP result. */
+async function runTool(argString) {
+  const { stdout, stderr, error } = await run(argString);
+  if (error) {
+    return errorResult(error.message, error.type);
+  }
+  const parts = [];
+  if (stdout) parts.push(stdout);
+  if (stderr) parts.push(`[stderr] ${stderr}`);
+  return text(parts.join("\n") || "(no output)");
+}
+
+// ---------------------------------------------------------------------------
+// Server
+// ---------------------------------------------------------------------------
+
+const server = new McpServer({
+  name: "obsidian-mcp",
+  version: "1.0.0",
+  capabilities: { tools: {} },
+});
+
+// ---- Generic pass-through tool ------------------------------------------
+
+server.tool(
+  "obsidian",
+  `Run any Obsidian CLI command. Pass the full command string exactly as you
+would on the terminal (minus the leading 'obsidian' binary name).
+Examples:
+  "daily:read"
+  "search:context query=\"meeting notes\" limit=5"
+  "read file=\"My Note\""
+  "tags counts sort=count"
+  "tasks daily"
+  "property:read name=status path=\"1p/my-project/my-project.md\""
+  "help search"`,
+  { command: z.string().describe("CLI command and arguments") },
+  async ({ command }) => runTool(command),
+);
+
+// ---- Convenience tools for common operations ----------------------------
+
+server.tool(
+  "obsidian_daily_read",
+  "Read today's daily note contents.",
+  {},
+  async () => runTool("daily:read"),
+);
+
+server.tool(
+  "obsidian_daily_path",
+  "Get the file path of today's daily note.",
+  {},
+  async () => runTool("daily:path"),
+);
+
+server.tool(
+  "obsidian_daily_append",
+  "Append content to today's daily note.",
+  { content: z.string().describe("Content to append") },
+  async ({ content }) => runTool(`daily:append content="${content.replace(/"/g, '\\"')}"`),
+);
+
+server.tool(
+  "obsidian_read",
+  "Read a note by file name (wikilink-style) or exact path.",
+  {
+    file: z.string().optional().describe("File name (wikilink resolution)"),
+    path: z.string().optional().describe("Exact file path"),
+  },
+  async ({ file, path }) => {
+    if (!file && !path) return text("Error: provide file= or path=");
+    const arg = file ? `file="${file}"` : `path="${path}"`;
+    return runTool(`read ${arg}`);
+  },
+);
+
+server.tool(
+  "obsidian_search",
+  "Full-text search across the vault with line context.",
+  {
+    query: z.string().describe("Search query"),
+    path: z.string().optional().describe("Limit to folder"),
+    limit: z.number().optional().describe("Max files to return"),
+  },
+  async ({ query, path, limit }) => {
+    let cmd = `search:context query="${query.replace(/"/g, '\\"')}"`;
+    if (path) cmd += ` path="${path}"`;
+    if (limit) cmd += ` limit=${limit}`;
+    return runTool(cmd);
+  },
+);
+
+server.tool(
+  "obsidian_tags",
+  "List tags in the vault with counts.",
+  {
+    sort: z.enum(["name", "count"]).optional().describe("Sort order"),
+  },
+  async ({ sort }) => {
+    let cmd = "tags counts";
+    if (sort) cmd += ` sort=${sort}`;
+    return runTool(cmd);
+  },
+);
+
+server.tool(
+  "obsidian_tasks",
+  "List tasks. Use daily=true for today's tasks only.",
+  {
+    daily: z.boolean().optional().describe("Show only daily note tasks"),
+    todo: z.boolean().optional().describe("Show incomplete tasks only"),
+    done: z.boolean().optional().describe("Show completed tasks only"),
+    path: z.string().optional().describe("Filter by file path"),
+  },
+  async ({ daily, todo, done, path }) => {
+    let cmd = "tasks";
+    if (daily) cmd += " daily";
+    if (todo) cmd += " todo";
+    if (done) cmd += " done";
+    if (path) cmd += ` path="${path}"`;
+    return runTool(cmd);
+  },
+);
+
+server.tool(
+  "obsidian_properties",
+  "List or read frontmatter properties.",
+  {
+    file: z.string().optional().describe("File name"),
+    path: z.string().optional().describe("File path"),
+    name: z.string().optional().describe("Specific property name to read"),
+  },
+  async ({ file, path, name }) => {
+    if (name && (file || path)) {
+      // Read a specific property from a specific file
+      const target = file ? `file="${file}"` : `path="${path}"`;
+      return runTool(`property:read name="${name}" ${target}`);
+    }
+    let cmd = "properties";
+    if (file) cmd += ` file="${file}"`;
+    if (path) cmd += ` path="${path}"`;
+    cmd += " counts";
+    return runTool(cmd);
+  },
+);
+
+server.tool(
+  "obsidian_create",
+  "Create a new note.",
+  {
+    name: z.string().optional().describe("File name"),
+    path: z.string().optional().describe("File path"),
+    content: z.string().optional().describe("Initial content"),
+    template: z.string().optional().describe("Template to use"),
+  },
+  async ({ name, path, content, template }) => {
+    let cmd = "create";
+    if (name) cmd += ` name="${name}"`;
+    if (path) cmd += ` path="${path}"`;
+    if (template) cmd += ` template="${template}"`;
+    if (content) cmd += ` content="${content.replace(/"/g, '\\"')}"`;
+    return runTool(cmd);
+  },
+);
+
+server.tool(
+  "obsidian_property_set",
+  "Set a frontmatter property on a note.",
+  {
+    name: z.string().describe("Property name"),
+    value: z.string().describe("Property value"),
+    file: z.string().optional().describe("File name"),
+    path: z.string().optional().describe("File path"),
+  },
+  async ({ name, value, file, path: filePath }) => {
+    const target = file ? `file="${file}"` : filePath ? `path="${filePath}"` : "";
+    if (!target) return text("Error: provide file= or path=");
+    return runTool(`property:set name="${name}" value="${value.replace(/"/g, '\\"')}" ${target}`);
+  },
+);
+
+server.tool(
+  "obsidian_backlinks",
+  "List backlinks to a note.",
+  {
+    file: z.string().optional().describe("File name"),
+    path: z.string().optional().describe("File path"),
+  },
+  async ({ file, path }) => {
+    const target = file ? `file="${file}"` : path ? `path="${path}"` : "";
+    return runTool(`backlinks ${target} counts`);
+  },
+);
+
+server.tool(
+  "obsidian_files",
+  "List files in the vault or a specific folder.",
+  {
+    folder: z.string().optional().describe("Filter by folder path"),
+    ext: z.string().optional().describe("Filter by extension"),
+  },
+  async ({ folder, ext }) => {
+    let cmd = "files";
+    if (folder) cmd += ` folder="${folder}"`;
+    if (ext) cmd += ` ext=${ext}`;
+    return runTool(cmd);
+  },
+);
+
+server.tool(
+  "obsidian_recents",
+  "List recently opened files.",
+  {},
+  async () => runTool("recents"),
+);
+
+// ---- Start ---------------------------------------------------------------
+
+async function main() {
+  const { running, version } = await checkObsidianRunning();
+  if (!running) {
+    console.error("Error: Obsidian is not running. Please open Obsidian and try again.");
+    process.exit(1);
+  }
+  const transport = new StdioServerTransport();
+  console.error(`obsidian-mcp server running on stdio (Obsidian ${version})`);
+  await server.connect(transport);
+}
+
+main().catch((err) => {
+  console.error("Fatal:", err);
+  process.exit(1);
+});