obsidian-mcp-server

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