obsidian rag mcp

Obsidian RAG with MCP

Goal: Give you practical MCP server options and repeatable workflows to turn a Git repository or Obsidian vault into an MCP-exposed RAG tool that Claude Code (and most MCP clients; Codex via emerging support) can use.

Fastest “Zero-Code” Patterns You Can Ship Today

1. Folder → MCP (read-only) via Filesystem server
   Use the official Filesystem MCP server to expose a directory of Markdown, code, and docs as MCP “resources” that the client can browse and attach to prompts. This is baseline context, not semantic RAG, but it is robust and safe.

2. GitHub repo → MCP via GitHub server
   Point Claude Code at the GitHub MCP server to read repos, issues, PRs, and code. You get repo search and resource URIs out of the box; pair with a RAG MCP server if you want semantic chunk retrieval.

3. Any Git repo → MCP via Git indexing servers
   Use “Git Repo Research MCP” (indexes remote repos with FAISS) or “git-mcp-server” (full git operations) when you need semantic search across repo content without cloning locally.

4. Obsidian vault → MCP
   Two main routes: (a) run an Obsidian-aware MCP server (e.g., mcp-obsidian or obsidian-mcp-server), or (b) treat the vault folder as a Filesystem server root and layer a RAG server on the same path. The Obsidian plugin approach gives you link resolution and metadata awareness.

5. Turn any folder/repo into semantic RAG via ready servers
   Run a RAG MCP server such as kb-mcp-server (txtai) or Contextual MCP; point it at your repo or vault to get embed, search, and cite tools exposed as MCP “tools” and “resources.”

Claude Code and Other Clients: Wiring and Ergonomics

• Claude Code ships native MCP support: add local stdio servers, remote HTTP, or SSE servers; manage servers with claude mcp add/list/get/remove. Project-scoped .mcp.json enables team-shareable configs.
• Cursor also supports MCP; it can discover and call server tools and resources the same way.
• Codex: OpenAI’s agent CLI has emerging MCP interop patterns. Official Agents SDK has MCP connectors; the Codex CLI has community and partner demos showing it paired with remote MCP servers, and the repo shows ongoing work. Treat Codex MCP as evolving.

Reference Workflow: Git Repo → “Semantic RAG” MCP Stack

1. Content adapter
   Choose the source: local repo path, remote git URL, or a mounted Obsidian vault. Implement a reader that: respects .gitignore, parses Markdown frontmatter, resolves wiki-links ([[note]]) and autogenerates canonical URIs (git://org/repo/path#L…).

2. Chunking and indexing
   Use Markdown-aware chunking by headings; store lexical index (SQLite FTS5 or tantivy) and embeddings (FAISS, pgvector, or vendor). Keep a reverse map from chunk → source URI + byte offsets for precise citations.

3. Tool surface (server “tools”)

   • rag.search(query, k, filters) → returns ranked chunks with URIs;
   • rag.read(uri, span) → fetch canonical source slices;
   • rag.cite(ids) → emit rich citations;
   • git.status()/git.blame()/git.show() if you include git tools for provenance.

4. Resource surface (server “resources”)
   Expose browsable collections like file://… for notes, git://… for code, and kb://… for precomputed topic views to make @mentions in clients work.

5. Hot-reload and CI
   Watch file changes and git pull; on change, re-chunk and update the vector store incrementally. Optional CI job to refresh the index nightly and push an artifacts snapshot.

6. Client config
   Claude Code: claude mcp add --transport http repo-rag http://localhost:7411/mcp then use /mcp__repo-rag__search or @resource mentions; project-scope with .mcp.json.

Obsidian-Specific Refinements

Use an Obsidian MCP server that understands vault frontmatter, backlinks, and embeds. For fully local setups, pair Filesystem server for raw file access with a RAG server pointed at the same vault root. Many setups use the Obsidian Local REST API plugin plus an MCP bridge.

Domain Add-ons for Bio RAG

If your repo or vault is bio/med heavy, append a domain MCP server like ToolUniverse to fetch drug targets, indications, ontologies, and curated APIs; your local RAG handles private notes, ToolUniverse supplies vetted biomedical tools.

Security, Ops, and Quality Controls That Matter

• Approvals: keep servers read-only for repos and vaults; use scoped tokens on any remote.
• Prompt-injection guardrails: strip HTML/JS in notes, add origin metadata, and require user confirmation for “write” tools.
• Eval: keep a small retrieval test set; log query → resources used → answer and measure precision@k and citation integrity.

Minimal Custom Server Blueprint (TypeScript)

// package.json deps: "@modelcontextprotocol/sdk": "^...",
// "faiss-node" or "pgvector", "gray-matter", "marked", "fastify"
import { Server } from "@modelcontextprotocol/sdk/server";
import { Tool } from "@modelcontextprotocol/sdk/types";
import matter from "gray-matter";
import { buildIndex, searchIndex, readSlice } from "./rag_index";

// 1) Start MCP server
const server = new Server({ name: "repo-rag", version: "0.1.0" });

// 2) Expose resources for @mentions (files, notes, prebuilt views)
server.addResourceProvider({
  listRoots: async () => [{ uri: "file://$REPO", name: "Repo root" }],
  listResources: async ({ uri }) => enumerateFiles(uri),         // md, code
  readResource: async ({ uri, range }) => readSlice(uri, range), // byte-safe
});

// 3) Expose RAG tools
const searchTool: Tool = {
  name: "rag.search",
  description: "Semantic+lexical search over repo/notes",
  inputSchema: { type: "object", properties: { query: { type: "string" }, k: { type: "integer", default: 8 } }, required: ["query"] },
  handler: async ({ query, k }) => searchIndex(query, k), // returns [{uri, title, snippet, score, spans}]
};
const citeTool: Tool = {
  name: "rag.cite",
  description: "Return canonical citations for chunk ids",
  inputSchema: { type: "object", properties: { ids: { type: "array", items: { type: "string" } } }, required: ["ids"] },
  handler: async ({ ids }) => ids.map(id => toCitation(id)),
};
server.addTool(searchTool);
server.addTool(citeTool);

// 4) Boot with initial index build + file watchers
await buildIndex({ root: process.env.REPO_PATH || "/data/repo" });
server.listenStdio(); // or .listenHttp({ port: 7411 });

Quick Picks: Which Route When

• Need simple context now for a vault or repo: Filesystem server.
• Need semantic search: pair Filesystem with kb-mcp-server or Contextual MCP.
• Need remote Git and PR context: GitHub MCP server.
• Need local Git ops and provenance: git-mcp-server plus your RAG server.
• Need Obsidian niceties: mcp-obsidian or obsidian-mcp-server plus RAG.