OB
SearchProductivitySecurity

Obsidian Markdown Vault Search MCP Server

Search and read your Obsidian vault or any Markdown directory with a fast, privacy-friendly MCP server.

View on GitHub
Quick Install
npx -y @calclavia/mcp-obsidian

Overview

Obsidian Markdown Vault Search MCP Server is a lightweight, privacy-oriented local server that exposes the contents of an Obsidian vault (or any directory of Markdown files) as searchable, structured context for language models and developer tools via the Model Context Protocol (MCP). Run it next to your vault to enable fast content lookup, snippet extraction, and file reading without uploading your notes to third-party services.

Because it runs locally and can be locked down to localhost, the server is suitable for workflows that require data privacy and low-latency access. It bridges the gap between LLMs and personal knowledge bases by providing programmatic search and read endpoints that adhere to the MCP tooling model, so agents and assistants can request relevant context on demand.

Features

  • Fast full‑text search across Markdown content and YAML frontmatter
  • File read endpoint that returns raw content or snippets
  • Respects directory layout and supports arbitrary Markdown folders (not limited to Obsidian)
  • Configurable indexing and optional filesystem watch for incremental updates
  • Simple token-based authentication and CORS configuration for secure local deployments
  • Small footprint; suitable for local machines or private servers
  • Exposes MCP-friendly tool endpoints so LLM agents can call search/read as tools

Installation / Configuration

Prerequisites: a recent Node.js runtime (e.g., Node 16+) or Docker (both options shown). Adjust commands to your environment if the project uses a different runtime.

Clone and run locally (Node.js):

git clone https://github.com/calclavia/mcp-obsidian.git
cd mcp-obsidian

# install dependencies (example with npm)
npm install

# start, using environment variables or a config file (examples below)
npm run start

Docker (example):

# build
docker build -t mcp-obsidian .

# run, mounting your vault into the container
docker run --rm -v /path/to/your/vault:/vault -e VAULT_PATH=/vault -e PORT=8080 -p 8080:8080 mcp-obsidian

Example configuration (config.json):

{
  "vaultPath": "/home/user/Notes",
  "port": 8080,
  "host": "127.0.0.1",
  "corsOrigins": ["http://localhost:3000"],
  "authToken": "replace-with-a-secret-token",
  "indexOnStart": true,
  "watch": true,
  "maxResults": 10
}

Environment variables (alternatively):

  • VAULT_PATH — path to your Markdown directory
  • PORT — server port (default: 8080)
  • HOST — bind interface (default: 127.0.0.1)
  • AUTH_TOKEN — bearer token for API access
  • INDEX_ON_START — true/false
  • WATCH — true/false

Security recommendations:

  • Keep HOST set to 127.0.0.1 for single-user setups.
  • Use a strong AUTH_TOKEN if exposing the server on a network.
  • Configure CORS only for trusted origins.

Available Tools / Resources

The server exposes a small set of MCP-style tools that are useful when integrating with LLM agents:

  • search
    • POST /mcp/search
    • Request body: { “query”: “text”, “limit”: 5, “filters”: { … } }
    • Response: list of hits with { path, title, excerpt, score, frontmatter }
  • read
    • POST /mcp/read
    • Request body: { “path”: “subdir/note.md”, “linesBefore”: 3, “linesAfter”: 3 }
    • Response: { path, content, excerpt }
  • list (optional)
    • GET /mcp/list
    • Returns a directory tree or flat list of files
  • metadata (optional)
    • GET /mcp/metadata?path=…
    • Returns parsed frontmatter and basic stats

Sample tool descriptor for LLM tool integration (JSON):

{
  "name": "obsidian_search",
  "description": "Search your local Obsidian vault for relevant notes
Tags:productivitysearchsecurity