Skip to main content
Glama
second-brain-mcp

second-brain-mcp

by nanthansr

second-brain-mcp

CI License: MIT Node >= 18

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.

Live session: index first, three budgeted reads, cited answer

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/vault

That 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/vault

Claude 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-mcp

Pointing 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

C:/Users/you/Documents/my-vault

macOS / Linux

/Users/you/Documents/my-vault

Notes:

  • An index.md at 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 to search_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 stamped read 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

get_index

Returns index.md, the one-line-per-page catalog. Call first.

free

tool

search_notes

Case-insensitive search, returns pages + line-numbered snippets

free

tool

read_note

Full content of one page by vault-relative path

counted

tool

list_recent

Pages modified in the last N days, newest first

free

resource

vault://index

The index as an MCP resource

free

prompt

vault-retrieval

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 VAULT_PATH env

bundled sample-vault/

Page read budget

VAULT_READ_BUDGET env

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.resolve first, then checked against the vault root - traversal attempts (../…) are rejected. Only .md files are readable.

  • Hard page budget. After N read_note calls (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)

npm test output: 15 checks, SMOKE PASS

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/, hide journal/)

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 tools
get_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

    A4.3/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Provides read-only access to an Obsidian vault, enabling file listing, content reading, and text search across notes via MCP.
      4
      2
      Apache 2.0
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to search, read, list, and append to markdown notes in a local Obsidian vault or folder of .md files.
      -
    • A
      license
      A
      quality
      C
      maintenance
      Enables natural language interaction with a local Obsidian vault, allowing MCP clients to read, search, create, append, and delete markdown notes securely.
      7
      MIT