secondbrain-mcp

A tiny Model Context Protocol server that exposes a folder of Markdown notes to an AI agent. Instead of pasting files into the prompt, the model can list, search, read, and append to your notes through real tool calls.

I built this because most "second brain" setups (Obsidian, a Drive folder of Markdown, Notion exports) are just files on disk. The useful question is how an agent reads and writes them reliably without you babysitting the context window. MCP is the clean answer: the notes become a typed tool surface the model can call.

What MCP is, in one line

MCP is an open protocol that lets an LLM client (Claude Desktop, Claude Code, ...) discover and call external tools and data over a simple JSON-RPC channel — wire a capability in once, and any MCP-aware client can use it.

Tools

Tool	What it does
list_notes	Every note with its title and size
search_notes(query)	Full-text search; returns the lines that match
read_note(name)	Full text of one note
append_note(name, text)	Append-only write — never silently rewrites

Run it

pip install -r requirements.txt
python server.py          # serves over stdio

Notes live in ./notes. Point it elsewhere with SECONDBRAIN_DIR=/path/to/vault.

Connect it to Claude

Drop this into Claude Desktop's claude_desktop_config.json or a project .mcp.json for Claude Code:

{
  "mcpServers": {
    "secondbrain": {
      "command": "python",
      "args": ["/abs/path/to/server.py"],
      "env": { "SECONDBRAIN_DIR": "/abs/path/to/your/vault" }
    }
  }
}

Then ask "search my notes for the deployment runbook" and the model calls search_notes instead of guessing.

How it fits together

flowchart LR
    A["Claude Desktop / Claude Code"] -- "MCP · JSON-RPC over stdio" --> B["secondbrain server"]
    B --> C[("notes/*.md")]
    B -. "list · search · read · append" .-> A

Design notes

• Append-only writes. append_note adds; it never overwrites. An agent can capture a thought without ever silently destroying a note.
• Plain Markdown is the source of truth. No database, no lock-in — the same folder works in Obsidian or a Git repo.
• stdio transport, so it drops into any local MCP client with zero network setup.

License

MIT