Obsidian Ts MCP

🚀 obsidian-ts-mcp

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

🚀 Quick Start

This obsidian-ts-mcp is an MCP server that wraps the official Obsidian CLI. It allows AI agents in VS Code and other MCP clients to perform operations such as reading, writing, searching, and managing notes in an Obsidian vault.

✨ Features

• Comprehensive Note Management: Offers a wide range of tools for note creation, reading, appending, prepending, and searching.
• Vault Information Retrieval: Provides tools to get vault details, list files, tags, and backlinks.
• Property and Metadata Handling: Allows setting and reading frontmatter properties of notes.
• Task Management: Enables listing and toggling tasks.
• Daily Note Operations: Supports operations on daily notes, including reading, appending, and prepending.
• Template Management: Lists and reads templates in the vault.
• Link and File Management: Lists outgoing links and moves/renames files while updating internal links.
• Project Management: Provides a set of tools for project creation, listing, overview, and backlog management.

📦 Installation

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

💻 Usage Examples

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

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

Environment Variables

📚 Documentation

Available Tools

The server exposes 37 tools organised into eleven groups:

Core -- note management

Discovery and context

Properties and metadata

Tasks

Daily notes (extended)

Templates

Links

Properties (extended)

Tags (extended)

File management

Bases

Project management

Project Structure

src/
  cli.ts          -- Low - level Obsidian CLI wrapper (exec, arg building, errors).
  fs-ops.ts       -- Direct filesystem operations (mkdir, read, write) for exact path control.
  tools.ts        -- MCP tool definitions (names, descriptions, JSON schemas).
  handlers.ts     -- Dispatches tool calls (37 tools) to CLI commands or filesystem ops.
  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.
  fs-ops.test.ts        -- Unit tests for filesystem operations.
  runObsidian.test.ts   -- Tests for CLI execution, timeouts, vault targeting.
  handlers.test.ts      -- Tests for all 37 tool handlers (CLI and fs - ops are 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 over stdio.
2. The client calls tools/list and receives the 37 tool definitions from src/tools.ts.
3. When the client invokes a tool, src/server.ts routes the call to handleTool() in src/handlers.ts.
4. handleTool() validates input against the tool schema, then either uses buildArgs() and runObsidian() from src/cli.ts to execute the corresponding obsidian CLI command, or uses direct filesystem operations from src/fs-ops.ts when exact path control is needed (e.g. creating notes in subdirectories, project management).
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 real Obsidian binary. Run:

npm test

Security Considerations

⚠️ Important Note

• Full vault access. The server has read/write access to every note in the targeted vault. Limit OBSIDIAN_VAULT to vaults you are comfortable exposing to AI agents.
• No authentication. The stdio transport has no built - in auth. Access control depends entirely on who can launch the server process.
• Input validation. All tool inputs are validated against their declared schemas before execution. The server uses execFile (not exec) to avoid shell injection, but note that file/path values are passed directly to the Obsidian CLI.
• Environment inheritance. The child process inherits the parent's environment variables. Avoid storing secrets in env vars visible to the server 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)

📄 License

MIT