Obsidian

You set up a read-only MCP server that lets any MCP client read and search through Markdown notes in a vault. This Obsidian MCP Server exposes a rich toolkit of obsidian_ tools to inspect tags, links, frontmatter, filenames, and full-text content across your vault, enabling powerful search and organization workflows from your preferred MCP client.

How to use

After you configure your MCP client to talk to the Obsidian MCP Server, you can perform a variety of actions directly against your vault. You can search for notes by filename, read note contents (with optional headers only), list and filter tags, find notes by tag, inspect frontmatter, discover backlinks, perform full-text searches, run natural-language queries, and count files within folders. Every operation is read-only and strictly confined to the vault directory.

Use the available tools through your MCP client by calling the obsidian_* tools. Typical workflows include locating notes related to a topic, quickly extracting note titles and structure, and building views of tag distributions or backlink networks to understand how your notes relate to each other.

How to install

Prerequisites ensure you can run the server locally:

Node.js (v18 or higher) and npm come with Node.js. You also need a directory containing Markdown notes (an Obsidian vault or similar).

Step 1. Clone the project repository

git clone https://github.com/dp-veritas/mcp-obsidian-tools.git
cd mcp-obsidian-tools

Step 2. Install dependencies

npm install

Step 3. Build the project

npm run build

Step 4. Run the server locally (example runtime command shown) and point it at your vault. The server is started via a standard Node invocation and the path to your vault is passed as an argument.

node /absolute/path/to/mcp-obsidian-tools/dist/index.js /absolute/path/to/your/vault

Configuration examples and how to connect

Configure your MCP client to connect to this local server. You can run the server directly or install it globally for easier access.

If you prefer to run the server as a locally-scoped process (node) with a vault path

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

Global installation option

If you want to install the tool globally so you can run it from anywhere, install it and configure a short form command.

Global install and minimal config example

npm install -g .

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

Available tools

obsidian_search_notes

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

obsidian_read_notes

Read contents of notes by relative path. Returns each note with its path header; reports failures per-note. Use headersOnly to return only headings.

obsidian_list_tags

Scan Markdown files to list all tags from frontmatter and inline tags, with occurrence counts. Optional startsWith filter.

obsidian_notes_by_tag

Return all note paths that contain given tags (frontmatter or inline). Optional match mode: any or all.

obsidian_get_frontmatter

Return parsed YAML frontmatter for a given note path as JSON.

obsidian_backlinks

List notes that link to a target note via wikilinks or markdown links.

obsidian_search_content

Full-text search inside note contents with optional wildcards. Can return paths or snippets with context.

obsidian_query

Natural-language query over the vault, with optional date filtering based on frontmatter dates.

obsidian_count_files

Count Markdown files in the vault or a subfolder; supports fuzzy folder lookup. Returns total and breakdown by subfolders; can include names.