Obsidian Model Context Protocol Tools

A Model Context Protocol (MCP) server that allows MCP clients (Cursor, VSCode, Claude Desktop, etc.) to read and search any directory containing Markdown notes, such as an Obsidian vault.

This server exposes a rich, read-only toolkit of obsidian_-prefixed MCP tools for working with vault metadata (tags, links, frontmatter), filenames, and full-text content.

Prerequisites

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

Installation

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 will compile the TypeScript code and create the dist/ directory with the executable files.

Configuration

After building, you need to add this server to your MCP client's configuration. The configuration format varies by client, but generally follows this pattern:

Quick Start: See example-mcp-config.json for Cursor/VSCode format, or example-claude-desktop-config.json for Claude Desktop format.

Configuration Format

Add an entry to your MCP client's configuration file (usually mcpServers or mcp.servers):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-obsidian-tools/dist/index.js", "/path/to/your/vault"]
    }
  }
}

Important: Use absolute paths for both the server location and your vault path.

Path Formats Supported

The vault path can be:

• Absolute path: /Users/username/Documents/MyVault
• Relative path: ./my-vault (relative to current working directory)
• Home directory shortcut: ~/Documents/MyVault

Example Configurations

For Cursor

Add to your Cursor MCP settings file (location varies by OS):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/Users/username/path/to/mcp-obsidian-tools/dist/index.js", "/Users/username/Documents/MyVault"]
    }
  }
}

For VSCode

Add to your User Settings JSON (Ctrl+Shift+P → Preferences: Open User Settings (JSON)) or create .vscode/mcp.json:

{
  "mcp": {
    "servers": {
      "obsidian": {
        "command": "node",
        "args": ["/Users/username/path/to/mcp-obsidian-tools/dist/index.js", "/Users/username/Documents/MyVault"]
      }
    }
  }
}

For Claude Desktop

Add to Claude Desktop's MCP configuration file (location varies by OS). Claude Desktop configs can include a preferences section:

{
  "preferences": {
    "quickEntryShortcut": {
      "accelerator": "Alt+Space"
    }
  },
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/Users/username/path/to/mcp-obsidian-tools/dist/index.js", "/Users/username/Documents/MyVault"]
    }
  }
}

Note: See example-claude-desktop-config.json for a complete Claude Desktop example. See example-mcp-config.json for Cursor/VSCode format.

Global Installation (Optional)

If you prefer to install globally so you can use it from anywhere:

npm install -g .

Then configure with:

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

Available Tools

Once configured, the following MCP tools will be available:

• obsidian_search_notes: Search for notes by filename (case-insensitive, supports simple regex / wildcards). Returns relative paths of matching .md files.

• obsidian_read_notes: Read the contents of multiple notes by relative path. Each note is returned with its path header; failures are reported per-note. Set headersOnly: true to return only headings (lines starting with #) for quick title/structure extraction.

• obsidian_list_tags: Scan all Markdown files and list all tags (frontmatter tags and inline #tags) with occurrence counts. Optional startsWith filter.

• obsidian_notes_by_tag: Given one or more tag names, return all note paths that contain those tags (frontmatter or inline). Optional match of "any" or "all".

• obsidian_get_frontmatter: Return parsed YAML frontmatter as JSON for a given note path (e.g. author, tags, created).

• obsidian_backlinks: Given a target note path or name, list all notes that link to it, via Obsidian wikilinks ([[Note Name]]) or markdown links ([Display](path)).

• obsidian_search_content: Full-text search inside note contents (not filenames). Supports simple wildcard patterns; can return just paths or snippets with context.

• obsidian_query: Natural-language query over the vault, with optional date filtering based on frontmatter dates (e.g. created: YYYY-MM-DDTHH:MM:SS).

• obsidian_count_files: Count the total number of markdown files in the vault or a specific subfolder. Supports fuzzy folder lookup - if a folder like "History 101" isn't at the root, automatically searches the entire vault for matching folders. Returns total count and breakdown by immediate subfolders. Set includeNames: true to also get a list of file names (up to 100). Useful for understanding vault size, organization, and listing files in a folder.

All tools are read-only and are strictly confined to the vault directory (and its real/symlinked path) via path validation.

Example obsidian_query Prompts

• Which of my entries concern the overton window?
• Show interview candidate notes I've logged from the last 6 months
• Any daily notes about board-related topics this month?

Troubleshooting

Server Not Starting

• Check paths: Ensure both the server path and vault path are absolute paths
• Verify build: Make sure you ran npm run build and the dist/ directory exists
• Check Node.js: Ensure Node.js v18+ is installed (node --version)

Tools Not Appearing

• Restart client: After adding the configuration, restart your MCP client (Cursor/VSCode/Claude Desktop)
• Check logs: Look for error messages in your MCP client's logs
• Verify vault path: Ensure the vault path is correct and accessible

Permission Errors

• Check vault permissions: Ensure you have read access to the vault directory
• Check server permissions: Ensure the dist/index.js file is executable (chmod +x dist/index.js)

Model Compatibility

Tool-calling quality depends on your LLM. Some models (especially smaller ones) may struggle to format correct parameters for MCP tools, particularly with:

• Complex natural language queries
• Non-English input
• Multiple parameters

If you encounter unexpected errors, try:

1. Simplifying your query
2. Using a larger/more capable model (i.e., Sonnet vs Haiku)
3. Checking that your MCP client is in the correct mode (i.e., Agent or Plan Mode in Cursor)

Note: Complex cross-referencing queries (e.g., "How does X relate to Y across my vault?") may require 10-30+ tool calls as the model iterates through different search strategies. This is normal behavior, not a failure.

Development

To watch for changes during development:

npm run watch

License

See LICENSE file for details.