Skip to main content
Glama
obsidian-rag-mcp

obsidian-rag-mcp

by shirokoweb

rag-obsidian-lmstudio

Fully local RAG over an Obsidian (or any markdown) vault, powered by LM Studio. Nothing leaves your machine.

Two ways to use it:

  • obsidian-rag — a terminal REPL: ask questions, get answers grounded in your notes with source citations.

  • obsidian-rag-mcp — an MCP server for the LM Studio GUI: the chat model gets a search_notes tool and answers from your vault, inside the app.

Indexing is incremental: only new or edited files are re-embedded on each run.

Prerequisites

  1. LM Studio with the local server running (Developer tab → Start Server, default http://localhost:1234).

  2. Two models loaded:

    • a chat model (e.g. any Gemma / Llama / Qwen instruct model)

    • an embedding model (e.g. nomic-embed-text-v1.5)

  3. Python ≥ 3.11 and uv (or pipx).

Related MCP server: obsidian-local-mcp

Install

uv tool install git+https://github.com/shirokoweb/rag-obsidian-lmstudio
# or: pipx install git+https://github.com/shirokoweb/rag-obsidian-lmstudio

Use the terminal REPL

obsidian-rag --docs-dir ~/path/to/your/vault
Chat:  google/gemma-4-e4b
Embed: text-embedding-nomic-embed-text-v1.5
Indexed 317 chunks from /Users/you/vault

Ask a question (blank line or Ctrl-D to quit).
? What is the CIA triad?

The CIA triad is a model that helps organizations consider risk ...

  sources: Module 2/25. Explore the CIA triad.md, ...
  top score: 0.830

Use inside LM Studio (MCP)

Add the server to LM Studio's mcp.json (Program tab → Install → Edit mcp.json):

{
  "mcpServers": {
    "obsidian-rag": {
      "command": "obsidian-rag-mcp",
      "env": {
        "RAG_DOCS_DIR": "/Users/you/path/to/your/vault"
      }
    }
  }
}

Then ask the chat model anything about your notes — it calls search_notes and answers grounded, with source filenames.

If LM Studio can't find the command, use the absolute path (which obsidian-rag-mcp) in the command field.

Configuration

CLI flags take precedence over environment variables.

Flag

Env var

Default

Purpose

--docs-dir

RAG_DOCS_DIR

(required)

Vault / notes directory

--base-url

RAG_BASE_URL

http://localhost:1234/v1

LM Studio server URL

--chat-model

RAG_CHAT_MODEL

auto-detect

Chat model id

--embed-model

RAG_EMBED_MODEL

auto-detect

Embedding model id

--top-k

RAG_TOP_K

4

Retrieved chunks per question (1–20)

Auto-detection picks the first loaded model whose id contains embed as the embedder and the first other model for chat. With several chat models loaded, set RAG_CHAT_MODEL explicitly.

The embedding cache lives in your OS user-cache directory (e.g. ~/Library/Caches/rag-obsidian-lmstudio on macOS) — never inside your vault. Deleting it is always safe; it will be rebuilt.

Troubleshooting

Symptom

Fix

Cannot reach LM Studio

Start the server: LM Studio → Developer tab → Start Server

Need both a chat and an embedding model loaded

Load an embedding model and a chat model in LM Studio

request timed out ... responding slowly

The chat model is too large/slow — set RAG_CHAT_MODEL to a smaller one

No documents directory configured

Pass --docs-dir or set RAG_DOCS_DIR

Stale answers after editing notes

Nothing to do — the index refreshes on every run/query

Privacy & security notes

  • All traffic goes to your configured LM Studio URL (localhost by default); there are no other network calls, no telemetry.

  • The cache uses plain JSON + NumPy .npz — no pickle, nothing executable.

  • The tool only ever reads your vault; it never writes into it.

Development

git clone https://github.com/shirokoweb/rag-obsidian-lmstudio
cd rag-obsidian-lmstudio
uv sync --all-extras
uv run pytest                 # tests
uv run ruff check . && uv run ruff format --check .
uv run mypy src               # typecheck

See SPEC.md for design decisions. MIT license.

Available Tools

1 tool
search_notesA

Search the user's markdown notes for passages relevant to the query. Use this for any question about the user's notes, then answer using only the returned passages and cite their source filenames.

Args: query: A natural-language question or topic to search for. top_k: How many passages to return (default 4, max 20).

Inputs: query (required), top_k. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 1 tool

    Disambiguation5/5

    With only one tool, there is no possibility of confusion between tools. The single tool's purpose is clear and distinct.

    Naming Consistency5/5

    The tool name 'search_notes' follows a clear verb_noun pattern. As the only tool, it is internally consistent.

    Tool Count3/5

    A single tool is borderline. It is not trivial and serves the core purpose of searching notes, but the tool surface feels thin for a server intended to support RAG over an entire note collection.

    Completeness4/5

    The search tool covers the primary retrieval need. Minor gaps exist, such as no ability to list all notes or fetch a specific note directly, but these can be worked around by searching with broad queries.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      A local MCP server that wraps the Obsidian CLI to give AI assistants direct access to read, edit, and manage notes within an Obsidian vault. It enables advanced operations such as frontmatter property management, context-aware searching, and the execution of internal Obsidian commands.
      2
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      An Obsidian plugin that runs an MCP server, enabling external LLM tools to read, search, create, and modify notes in your vault via HTTP or stdio transport.
      44
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides natural language access to an Obsidian vault, enabling reading, searching, listing, and creating notes.
      -