obsidian-ts-mcp

obsidian-ts-mcp

A Model Context Protocol (MCP) server that wraps the official Obsidian CLI,letting AI agents in VS Code (and any other MCP client) read, write, search,and manage notes inside an Obsidian vault.

Prerequisites

The Obsidian desktop app must be running when the MCP server is in use.The obsidian binary must be available on your PATH.

Installation

git clone https://github.com/dickiedyce/obsidian-ts-mcp.git
cd obsidian-ts-mcp
npm install
npm run build

Configuration

VS Code (user-level MCP)

Add the following to your VS Code MCP configuration:

{
  "servers": {
    "obsidian": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json(~/Library/Application Support/Claude/claude_desktop_config.json on macOS,%APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT": "My Vault"
      }
    }
  }
}

Set OBSIDIAN_VAULT to the name of the vault you want to target. The namemust match exactly what Obsidian shows in the vault switcher.

Environment variables

Available tools

The server exposes 16 tools organised into four groups.

Core -- note management

Discovery and context

Properties and metadata

Tasks

Project structure

src/
  cli.ts          -- Low-level Obsidian CLI wrapper (exec, arg building, errors).
  tools.ts        -- MCP tool definitions (names, descriptions, JSON schemas).
  handlers.ts     -- Dispatches tool calls to the appropriate CLI commands.
  server.ts       -- MCP server entry-point (stdio transport, error handling).
  validation.ts   -- Input validation against tool schemas.
tests/
  cli.test.ts           -- Unit tests for argument building and error types.
  runObsidian.test.ts   -- Tests for CLI execution, timeouts, vault targeting.
  handlers.test.ts      -- Tests for all 16 tool handlers (CLI is mocked).
  tools.test.ts         -- Schema validation for every tool definition.
  validation.test.ts    -- Input validation tests (types, enums, required fields).
  server.test.ts        -- Server factory, error formatting, version checks.

Development

npm run dev           # Watch-mode TypeScript compilation
npm test              # Run the test suite once
npm run test:watch    # Run tests in watch mode
npm run test:coverage # Run tests with coverage report
npm run build         # One-shot compilation
npm run lint          # Run ESLint
npm run format:check  # Check Prettier formatting
npm start             # Start the MCP server on stdio

How it works

1. An MCP client (VS Code, Claude Desktop, etc.) launches the server overstdio.
2. The client calls tools/list and receives the 16 tool definitions fromsrc/tools.ts.
3. When the client invokes a tool, src/server.ts routes the call tohandleTool() in src/handlers.ts.
4. handleTool() validates input against the tool schema, then usesbuildArgs() and runObsidian() from src/cli.ts to execute thecorresponding obsidian CLI command.
5. The CLI output is returned to the client as a text content block.

Testing

Tests use Vitest and mock the CLI layer so they never invoke the realObsidian binary. Run:

npm test

Security considerations

• Full vault access. The server has read/write access to every note in thetargeted vault. Limit OBSIDIAN_VAULT to vaults you are comfortableexposing to AI agents.
• No authentication. The stdio transport has no built-in auth. Accesscontrol depends entirely on who can launch the server process.
• Input validation. All tool inputs are validated against their declaredschemas before execution. The server uses execFile (not exec) to avoidshell injection, but note that file/path values are passed directly to theObsidian CLI.
• Environment inheritance. The child process inherits the parent'senvironment variables. Avoid storing secrets in env vars visible to theserver process.

Troubleshooting

Symptom: obsidian: command not found Cause: CLI binary not on PATH Fix: Ensure Obsidian 1.12+ is installed and the CLI is enabled in Settings > General

Symptom: Command timed out after 15000ms Cause: Obsidian desktop app not running Fix: Start the Obsidian app before using the MCP server

Symptom: vault not found Cause: Vault name mismatch Fix: Check that OBSIDIAN_VAULT matches the exact name in Obsidian’s vault switcher

Symptom: Catalyst licence required Cause: Missing licence Fix: The Obsidian CLI requires a Catalyst licence — purchase one at obsidian.md

Symptom: Server exits immediately Cause: Node.js version too old Fix: Ensure Node.js >= 18 (node --version)

Licence

MIT