# secondbrain-mcp

A tiny [Model Context Protocol](https://modelcontextprotocol.io) 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

```bash
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:

```json
{
  "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

```mermaid
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