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

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.

obsidian-mcp-pro

obsidian-mcp-pro

Features

Read & Search

Write & Modify

Tags

Links & Graph

Canvas

MCP Resources

Quick Start

Claude Desktop

Claude Code

Configuration

Tool Reference

MCP Resources

Development

Project Structure

Testing

License

Contributing

Reviews