second-brain-mcp
Provides read-only access to an Obsidian vault, with tools for indexing, searching, reading notes, and listing recently modified pages while enforcing a page-read budget and path sandbox.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@second-brain-mcp What are my notes about the Q3 pricing proposal?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
second-brain-mcp
A read-only MCP server for any Obsidian or plain-markdown vault, with the retrieval protocol enforced by the server instead of requested in prose.
Point it at a folder of markdown notes and every MCP client - Claude Code, Claude Desktop, Cursor, anything - can query that knowledge base through four governed tools. The server physically cannot write, cannot leave the vault directory, and cuts a session off after a hard budget of page reads.
Why
Personal knowledge bases end up welded to one tool. The notes live in Obsidian; the AI assistant that could use them lives somewhere else, so you copy-paste. And when an assistant does get file access, "please read only what you need" is a politeness request, not a rule.
This server fixes both:
One connector, every app. MCP is the USB-C of AI tools - write the vault connector once and any MCP client can use it.
The protocol is law, not a suggestion. Index-first retrieval, a hard page-read budget, read-only access, and a path sandbox are enforced in code. The only operations that exist are the governed ones.
Related MCP server: obsidian-gate
Install
Requires Node.js 18 or newer.
Option A - from npm
claude mcp add second-brain -- npx -y @nanthansr/second-brain-mcp /abs/path/to/your/vaultThat single command registers the server with Claude Code; npx fetches and runs the package automatically. For other clients, see the config blocks below.
Option B - from source
git clone https://github.com/nanthansr/second-brain-mcp
cd second-brain-mcp
npm install && npm run build
npm test # 15-check integration suite - should end with SMOKE PASS
claude mcp add second-brain -- node /abs/path/to/second-brain-mcp/dist/index.js /abs/path/to/your/vaultClaude Desktop
Add to claude_desktop_config.json (Settings → Developer → Edit Config):
{
"mcpServers": {
"second-brain": {
"command": "npx",
"args": ["-y", "@nanthansr/second-brain-mcp", "/abs/path/to/your/vault"]
}
}
}Cursor
Add the same block to ~/.cursor/mcp.json (or Cursor Settings → MCP → Add new server).
No vault handy?
Omit the vault argument entirely and the server serves its bundled fictional demo vault ("Alex Rivera") - useful for trying it in 30 seconds:
claude mcp add second-brain-demo -- npx -y @nanthansr/second-brain-mcpPointing it at your Obsidian vault
Your vault is just a folder - the one you picked when Obsidian said "Open folder as vault". Pass that folder's absolute path as the argument:
OS | Example |
Windows |
|
macOS / Linux |
|
Notes:
An
index.mdat the vault root unlocks the index-first flow (get_index): a catalog page with one line per note. If you don't have one, everything still works - the model falls back tosearch_notes.Obsidian's own config (
.obsidian/) and any other dotfolders are invisible to the server.The server never modifies anything - Obsidian can stay open while it runs.
Usage
Once connected, just ask questions. Typical flows (from a real session against the demo vault):
"What is Alex Rivera working on and who is Sam?" →
get_index→read_note×3 (each stampedread 1/5,read 2/5,read 3/5) → cited answer.
"What changed in my vault this week?" →
list_recent(days: 7)→ dated list, newest first.
"Where do I keep my notes about pricing?" →
search_notes(query: "pricing")→ matching pages with line-numbered snippets, no budget spent.
Clients that support MCP prompts also get vault-retrieval - a slash-command template that pins the model to the index-first protocol for a given question.
What the client gets
Kind | Name | What it does | Budget |
tool |
| Returns | free |
tool |
| Case-insensitive search, returns pages + line-numbered snippets | free |
tool |
| Full content of one page by vault-relative path | counted |
tool |
| Pages modified in the last N days, newest first | free |
resource |
| The index as an MCP resource | free |
prompt |
| The index-first protocol as a reusable prompt template | - |
The intended flow mirrors how a careful human uses a wiki: read the catalog, open the one or two pages that matter, answer with citations. Locating is cheap; reading is budgeted.
Configuration
Setting | How | Default |
Vault path | first CLI argument, or | bundled |
Page read budget |
| 5 per session |
Security model
Read-only by construction. No write, edit, or delete tool exists in the codebase.
Path sandbox. Every path is canonicalized with
path.resolvefirst, then checked against the vault root - traversal attempts (../…) are rejected. Only.mdfiles are readable.Hard page budget. After N
read_notecalls (default 5) the server refuses further reads and tells the model to synthesize from what it has. Failed reads do not consume budget.Size caps. Notes truncate at 50KB; search results and recency lists are capped.
Dotfolders skipped.
.obsidian,.git, and other dotfolders are invisible.Code is public, data is not. The repo contains only server code and a fictional demo vault. Your real vault is whatever folder you mount at runtime; it never leaves your machine.
FAQ
Does my data leave my machine? No. The server runs locally as a child process of your MCP client and reads files from disk. There is no network code in it.
Can it modify or delete my notes? No. There is no tool that writes. This is a property of the code, not a setting.
What happens when the model hits the budget? The 6th read returns an error telling the model to synthesize from the pages it already has. A new conversation gets a fresh budget.
Why did the demo answer talk about "Alex Rivera"? You're on the bundled fictional demo vault. Pass your own vault path as the first argument.
Development
npm run build # tsc -> dist/
npm test # build + 15-check smoke test (spawns the real server over stdio)The smoke test uses the SDK's own client against the compiled server - real protocol, no mocks. It verifies all four tools, the resource, the prompt, path-traversal rejection, and that the read budget refuses the N+1th read. CI runs it on Linux and Windows, Node 20 and 22.
Curious why it's built this way? See docs/design-notes.md - transports, the three MCP primitives, schemas-as-prompts, and the sandbox and budget decisions.
Roadmap
Remote variant (streamable HTTP) so the vault is reachable from hosted clients, with auth
Optional per-folder scoping (serve only
wiki/, hidejournal/)
Contributing
Issues and PRs welcome. Keep the invariants: no write tools, no network calls, the smoke test stays green and unweakened.
License
MIT · Changes in CHANGELOG.md
Available Tools
4 toolsget_indexGet the vault indexA
Returns index.md, the catalog of every page in the vault (one line each). ALWAYS call this first to locate relevant pages, then read only the 1-2 pages that matter. Does not count against the page budget.
Inputs: no named parameters.
list_recentList recently updated pagesA
Lists pages modified in the last N days (default 7), newest first. Good for 'what changed lately'. Does not count against the page budget.
Inputs: days.
read_noteRead one pageA
Returns the full content of one markdown page by vault-relative path (e.g. wiki/people/sam-okafor.md). Counts against the hard page budget of 5 reads per session - locate pages via get_index or search_notes first, then read only what matters.
Inputs: path (required).
search_notesSearch the vaultA
Case-insensitive text search across every markdown page. Returns matching pages with line-numbered snippets. Use when the index does not answer 'where does this live'. Does not count against the page budget.
Inputs: query (required), max_results.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct role: index for catalog lookup, search for text search, read for content retrieval, and list_recent for recency. The descriptions even specify when to prefer one over another, removing ambiguity.
All tool names use snake_case with an imperative verb first, creating a predictable pattern. list_recent is slightly less parallel than list_recent_notes, but the deviation is minor and does not confuse the set.
Four tools is well-scoped for a retrieval-focused note vault: discovery via index/search/recent and content access via read. Each tool serves a distinct workflow step with no redundancy.
The surface fully covers read-oriented workflows: locating notes, finding content by text, checking recent changes, and reading full pages. The only notable gap is write/edit operations, but the tool descriptions consistently frame this as a read-only vault interface.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides read-only access to an Obsidian vault, enabling file listing, content reading, and text search across notes via MCP.42Apache 2.0
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to read, search, write, and link notes in an Obsidian vault via MCP tools and resources.MIT
- FlicenseNot gradedqualityCmaintenanceEnables MCP clients to search, read, list, and append to markdown notes in a local Obsidian vault or folder of .md files.-
- AlicenseAqualityCmaintenanceEnables natural language interaction with a local Obsidian vault, allowing MCP clients to read, search, create, append, and delete markdown notes securely.7MIT