obsidian-mcp

README

obsidian-mcp

A Model Context Protocol (MCP) server that enables AI assistants to read, write, and search your Obsidian vault.

Features

• Full vault access — Read, write, edit, delete, rename, list, and search notes
• Vault discovery — Browse folders before opening a note
• Frontmatter support — Parse and update YAML frontmatter seamlessly
• Security first — Path traversal prevention, blocked system directories, safe defaults
• Token optimized — Compact JSON responses for efficient AI interactions
• Universal compatibility — Works with any MCP-compatible AI (Claude, ChatGPT, etc.)

Installation

go install github.com/taigrr/obsidian-mcp/cmd/obsidian-mcp@latest

Or build from source:

git clone https://github.com/taigrr/obsidian-mcp.git
cd obsidian-mcp
go build -o obsidian-mcp ./cmd/obsidian-mcp

Usage

obsidian-mcp /path/to/your/vault

MCP Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp",
      "args": ["/path/to/your/vault"]
    }
  }
}

Tools

Tool	Description
read	Read a note with frontmatter and content. Supports pagination.
write	Create or overwrite a note with content and optional frontmatter.
edit	Replace text and/or update frontmatter fields in an existing note.
delete	Delete a note (requires confirmation).
rename	Move or rename a note to a new path.
search	Full-text search with regex support. Returns matches with context.
related	Find notes related by tags or wiki-links.
tags	List all unique tags across the vault (frontmatter and inline).
list	List files and subdirectories in a vault directory.

Examples

Reading a note

{
  "tool": "read",
  "arguments": {
    "path": "notes/my-note.md"
  }
}

Writing a note with frontmatter

{
  "tool": "write",
  "arguments": {
    "path": "notes/new-note.md",
    "content": "# My Note\n\nThis is the content.",
    "frontmatter": {
      "tags": ["idea", "project"],
      "status": "draft"
    }
  }
}

Searching the vault

{
  "tool": "search",
  "arguments": {
    "query": "TODO",
    "contextLines": 2
  }
}

Listing a folder

{
  "tool": "list",
  "arguments": {
    "path": "projects"
  }
}

Editing a note

{
  "tool": "edit",
  "arguments": {
    "path": "notes/my-note.md",
    "oldText": "draft",
    "newText": "published",
    "frontmatter": {
      "status": "published"
    }
  }
}

Security

• Path filtering — Blocks access to .obsidian/, .git/, node_modules/, and system files
• File type restrictions — Only allows .md, .markdown, and .txt files
• Path traversal prevention — All paths validated to stay within vault boundaries
• Confirmation required — Destructive operations require explicit confirmation

Development

go build ./...        # Build
go test ./...         # Test
go vet ./...          # Lint

License

0BSD — Tai Groot