mcp-obsidian-tools

The Obsidian Model Context Protocol Tools MCP server provides read-only access to an Obsidian vault (or any directory containing Markdown notes) via MCP. It exposes a rich set of obsidian_ tools designed to help clients search, inspect, and analyze vault content without modifying files. Available tools include: obsidian_search_notes for filename-based searches, obsidian_read_notes to fetch note contents (with optional headersOnly for quick structure extraction), obsidian_list_tags to enumerate tags with counts, obsidian_notes_by_tag to find notes by tag, obsidian_get_frontmatter to retrieve YAML frontmatter, obsidian_backlinks to discover linking notes, obsidian_search_content for full-text content search, obsidian_query for natural-language vault queries, and obsidian_count_files to gauge vault size by folder. These tools enable comprehensive vault exploration, metadata extraction, and content discovery in a read-only, secure manner restricted to the configured vault path.

To use it from an MCP client (e.g., Cursor, VSCode, Claude Desktop), configure a server entry that points to the Node.js runtime and the built distribution of this tool, along with the absolute path to your vault. Once configured, invoke the obsidian_* tools with appropriate parameters as described by your client’s MCP interface. Path handling requires absolute paths for both the server runtime and the vault, ensuring the MCP server can safely access only the intended directory.

Prerequisites:

• Node.js v18 or higher
• npm (comes with Node.js)
• An Obsidian vault or directory containing Markdown files

Installation steps:

1. Clone the repository: git clone https://github.com/dp-veritas/mcp-obsidian-tools.git cd mcp-obsidian-tools

2. Install dependencies: npm install

3. Build the project: npm run build

   This compiles the TypeScript source and outputs the executable distribution files to the dist/ directory.

4. Run the server locally (example): node dist/index.js path/to/your/vault

   Note: The exact invocation may vary depending on how you deploy; use the mcp_config guidance to point to the built dist/index.js and your vault.

Tips and considerations:

• Ensure Node.js v18+ is installed and accessible in PATH.
• Use absolute paths for both the server executable (dist/index.js) and the vault directory in MCP client configurations.
• The server is read-only and restricts access to the vault directory (and its real/symlinked path) for security.
• If you encounter issues where tools don’t appear in your MCP client, restart the client after updating configurations and verify vault path accessibility.
• If you run globally (npm install -g .), configure the server with command "mcp-obsidian-tools" and provide the vault path as an argument per the global configuration example.
• For large vaults, consider using obsidian_count_files to understand vault size and structure before running content-wide searches.