Obsidian MCP Server

A Model Context Protocol (MCP) server for Obsidian vault operations. Works with any MCP-compatible client including Claude Desktop, Cursor, Windsurf, and VS Code.

Features

• Full Vault Access: Read, write, search, and delete notes
• Link Navigation: Get outgoing links and backlinks for any note
• Tag Management: List all tags, find notes by tag
• Flexible Search: Search by content, title, tags, or folder
• Two Transports: Stdio (local) or Streamable HTTP (remote)
• Modern MCP: Built with MCP SDK 1.6.1, Zod validation, tool annotations

Quick Start

# Install dependencies
npm install

# Build
npm run build

# Run (stdio mode)
OBSIDIAN_VAULT_PATH=/path/to/vault npm start

# Run (HTTP mode)
OBSIDIAN_VAULT_PATH=/path/to/vault npm run start:http

Configuration

Environment Variables

Variable	Required	Default	Description
OBSIDIAN_VAULT_PATH	Yes	-	Absolute path to your Obsidian vault
TRANSPORT	No	stdio	Transport mode: stdio or http
PORT	No	3000	HTTP server port
HOST	No	127.0.0.1	HTTP server host
DEBUG	No	false	Enable debug logging

MCP Client Configuration

Claude Desktop / Cursor / Windsurf (stdio)

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

HTTP Mode

Start the server:

OBSIDIAN_VAULT_PATH=/path/to/vault TRANSPORT=http npm start

Connect via http://localhost:3000/mcp

Available Tools

Note Operations

Tool	Description
obsidian_list_notes	List notes with pagination and folder filtering
obsidian_read_note	Read a note's full content and metadata
obsidian_write_note	Create or update a note
obsidian_delete_note	Permanently delete a note
obsidian_search_notes	Search notes by content, tags, or folder

Vault Information

Tool	Description
obsidian_vault_stats	Get vault statistics (note count, size, etc.)
obsidian_list_tags	List all tags with usage counts
obsidian_get_tagged_notes	Get all notes with a specific tag

Link Navigation

Tool	Description
obsidian_get_links	Get outgoing links from a note
obsidian_get_backlinks	Get backlinks to a note

Response Formats

All tools support a response_format parameter:

• json (default): Structured JSON data
• markdown: Human-readable markdown

Development

# Development mode (with auto-reload)
npm run dev

# Build
npm run build

# Test (builds and runs --help)
npm test

Project Structure

src/
  index.ts      # Entry point, transport handling
  server.ts     # MCP server with tool registrations
  vault.ts      # Vault operations (CRUD, search, links)
  schemas.ts    # Zod input validation schemas
  types.ts      # TypeScript type definitions

License

MIT