obsidian-mcp-pro

The most feature-complete MCP server for Obsidian vaults.

Give AI assistants deep, structured access to your Obsidian knowledge base. Read, write, search, tag, analyze links, traverse graphs, and manipulate canvases — all through the Model Context Protocol.

---

Features

Read & Search

• Full-text search across all vault notes
• Read individual notes with frontmatter parsing
• List and filter notes by folder, date, or pattern
• Search by frontmatter fields and values
• Retrieve daily notes automatically

Write & Modify

• Create new notes with frontmatter and content
• Append or prepend content to existing notes
• Update frontmatter properties programmatically
• Move and rename notes with automatic link updates
• Delete notes safely

Tags

• Build and query a complete tag index
• Search notes by single or multiple tags

Links & Graph

• Get backlinks (what links to a note)
• Get outlinks (what a note links to)
• Find orphan notes with no inbound or outbound links
• Detect broken links pointing to non-existent notes
• Traverse graph neighbors to a configurable depth

Canvas

• Read .canvas files with full node and edge data
• Add new nodes (text, file, link, group) to canvases
• Add edges between canvas nodes
• List all canvases in the vault

MCP Resources

• obsidian://note/{path} — read any note by its vault-relative path
• obsidian://tags — retrieve the full tag index as JSON
• obsidian://daily — get today's daily note content

---

Quick Start

Claude Desktop

Add this to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-pro"]
    }
  }
}

If you have multiple vaults, specify which one:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-pro"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Claude Code

claude mcp add obsidian-mcp-pro -- npx -y obsidian-mcp-pro

---

Configuration

The server locates your vault using the following priority:

Priority	Method	Description
1	OBSIDIAN_VAULT_PATH	Environment variable with the absolute path to your vault
2	OBSIDIAN_VAULT_NAME	Environment variable to select a vault by folder name when multiple vaults exist
3	Auto-detection	Reads Obsidian's global config (obsidian.json) and uses the first valid vault found

Auto-detection works on macOS, Windows, and Linux by reading the platform-specific Obsidian configuration directory.

---

Tool Reference

Tool	Description	Key Parameters
search_notes	Full-text search across all notes	query, caseSensitive, maxResults, folder
get_note	Read a note's content and metadata	path
list_notes	List notes in the vault or a folder	folder, limit
get_daily_note	Get today's (or a specific date's) daily note	date
search_by_frontmatter	Find notes by frontmatter property values	property, value, folder
create_note	Create a new note with content and frontmatter	path, content, frontmatter
append_to_note	Append content to an existing note	path, content, ensureNewline
prepend_to_note	Prepend content after frontmatter	path, content
update_frontmatter	Update frontmatter properties on a note	path, properties
create_daily_note	Create today's daily note from template	date, content, templatePath
move_note	Move or rename a note	oldPath, newPath
delete_note	Delete a note from the vault	path, permanent
get_tags	Get all tags and their usage counts	sortBy
search_by_tag	Find all notes with a specific tag	tag, includeContent
get_backlinks	Get all notes that link to a given note	path
get_outlinks	Get all links from a given note	path
find_orphans	Find notes with no links in or out	includeOutlinksCheck
find_broken_links	Detect links pointing to non-existent notes	folder
get_graph_neighbors	Get notes connected within N link hops	path, depth, direction
list_canvases	List all .canvas files in the vault	—
read_canvas	Read a .canvas file's nodes and edges	path
add_canvas_node	Add a node to a canvas	canvasPath, type, content, x, y
add_canvas_edge	Add an edge between two canvas nodes	canvasPath, fromNode, toNode

---

MCP Resources

Resources provide a URI-based way to access vault data:

Resource URI	Description
obsidian://note/{path}	Read any note by its vault-relative path
obsidian://tags	Full tag index with file lists (JSON)
obsidian://daily	Today's daily note content

---

Development

# Clone the repository
git clone https://github.com/rps321321/obsidian-mcp-pro.git
cd obsidian-mcp-pro

# Install dependencies
npm install

# Build
npm run build

# Run in development (watch mode)
npm run dev

# Start the server locally
OBSIDIAN_VAULT_PATH=/path/to/vault npm start

Project Structure

src/
  index.ts          # Server entry point and resource registration
  config.ts         # Vault detection and configuration
  types.ts          # Shared TypeScript interfaces
  lib/
    vault.ts        # Core vault operations (read, search, list)
    markdown.ts     # Frontmatter parsing and tag extraction
  tools/
    read.ts         # Search, get, list, daily note tools
    write.ts        # Create, append, prepend, update, move, delete tools
    tags.ts         # Tag index and tag search tools
    links.ts        # Backlinks, outlinks, orphans, broken links, graph tools
    canvas.ts       # Canvas read, node, edge, and list tools

---

Testing

npm test

122 tests covering vault operations, markdown parsing (frontmatter, wikilinks, tags, code block detection), and integration tests with a mock vault.

License

MIT

---

Contributing

Contributions welcome! Please open an issue first to discuss what you'd like to change. Pull requests without a corresponding issue may be closed.