second-brain-mcp

Ein schreibgeschützter MCP-Server für beliebige Obsidian- oder Plain-Markdown-Vaults, bei dem das Retrieval-Protokoll vom Server erzwungen wird, statt in Prosa angefragt zu werden.

Richte ihn auf einen Ordner mit Markdown-Notizen aus, und jeder MCP-Client – Claude Code, Claude Desktop, Cursor, was auch immer – kann diese Wissensbasis über vier kontrollierte Tools abfragen. Der Server kann physisch nicht schreiben, kann das Vault-Verzeichnis nicht verlassen und bricht eine Sitzung nach einem harten Budget an Seitenlesevorgängen ab.

Warum

Persönliche Wissensbasen enden damit, an ein einziges Tool gekettet zu sein. Die Notizen leben in Obsidian; der KI-Assistent, der sie nutzen könnte, lebt woanders, also kopierst du und fügst ein. Und wenn ein Assistent doch Dateizugriff bekommt, ist „lies bitte nur, was du brauchst“ eine Höflichkeitsbitte, keine Regel.

Dieser Server behebt beides:

• Ein Connector, jede App. MCP ist das USB-C der KI-Tools – schreibe den Vault-Connector einmal und jeder MCP-Client kann ihn nutzen.

• Das Protokoll ist Gesetz, kein Vorschlag. Index-zuerst-Retrieval, ein hartes Seiten-Lesebudget, schreibgeschützter Zugriff und eine Pfad-Sandbox sind im Code erzwungen. Die einzigen Operationen, die existieren, sind die kontrollierten.

Related MCP server: obsidian_mcp

Installation

Erfordert Node.js 18 oder neuer.

Option A – von npm

claude mcp add second-brain -- npx -y @nanthansr/second-brain-mcp /abs/path/to/your/vault

Dieser einzelne Befehl registriert den Server bei Claude Code; npx holt und führt das Paket automatisch aus. Für andere Clients siehe die Konfigurationsblöcke unten.

Option B – aus dem Quellcode

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

Füge zu claude_desktop_config.json hinzu (Einstellungen → Entwickler → Konfiguration bearbeiten):

{
  "mcpServers": {
    "second-brain": {
      "command": "npx",
      "args": ["-y", "@nanthansr/second-brain-mcp", "/abs/path/to/your/vault"]
    }
  }
}

Cursor

Füge denselben Block zu ~/.cursor/mcp.json hinzu (oder Cursor-Einstellungen → MCP → Neuen Server hinzufügen).

Kein Vault zur Hand?

Lass das Vault-Argument komplett weg und der Server bedient sein gebündeltes fiktives Demo-Vault („Alex Rivera“) – nützlich, um es in 30 Sekunden auszuprobieren:

claude mcp add second-brain-demo -- npx -y @nanthansr/second-brain-mcp

Auf deinen Obsidian-Vault ausrichten

Dein Vault ist einfach ein Ordner – der, den du gewählt hast, als Obsidian „Ordner als Vault öffnen“ sagte. Übergib den absoluten Pfad dieses Ordners als Argument:

Hinweise:

• Ein index.md im Vault-Root schaltet den Index-zuerst-Ablauf frei (get_index): eine Katalogseite mit einer Zeile pro Notiz. Wenn du keinen hast, funktioniert trotzdem alles – das Modell weicht auf search_notes aus.

• Obsidians eigene Konfiguration (.obsidian/) und alle anderen Dot-Ordner sind für den Server unsichtbar.

• Der Server ändert nie etwas – Obsidian kann geöffnet bleiben, während er läuft.

Verwendung

Sobald du verbunden bist, stell einfach Fragen. Typische Abläufe (aus einer echten Sitzung mit dem Demo-Vault):

„Woran arbeitet Alex Rivera und wer ist Sam?“ → get_index → read_note ×3 (jeweils mit read 1/5, read 2/5, read 3/5 gestempelt) → zitierte Antwort.

„Was hat sich diese Woche in meinem Vault geändert?“ → list_recent(days: 7) → datierte Liste, neueste zuerst.

„Wo bewahre ich meine Notizen zum Thema Preisgestaltung auf?“ → search_notes(query: "pricing") → passende Seiten mit zeilennummerierten Ausschnitten, kein Budget verbraucht.

Clients, die MCP-Prompts unterstützen, erhalten außerdem vault-retrieval – eine Slash-Command-Vorlage, die das Modell für eine bestimmte Frage auf das Index-zuerst-Protokoll festlegt.

Was der Client bekommt

Der vorgesehene Ablauf spiegelt wider, wie ein sorgfältiger Mensch ein Wiki benutzt: Katalog lesen, die ein oder zwei relevanten Seiten öffnen, mit Zitaten antworten. Lokalisieren ist günstig; Lesen ist budgetiert.

Konfiguration

Sicherheitsmodell

• Konstruktionsbedingt schreibgeschützt. Im Codebase existiert kein Tool zum Schreiben, Bearbeiten oder Löschen.

• Pfad-Sandbox. Jeder Pfad wird zuerst mit path.resolve kanonisiert und dann gegen das Vault-Root geprüft – Traversal-Versuche (../…) werden abgelehnt. Nur .md-Dateien sind lesbar.

• Hartes Seitenbudget. Nach N read_note-Aufrufen (Standard 5) verweigert der Server weitere Lesevorgänge und weist das Modell an, aus dem zu synthetisieren, was es bereits hat. Fehlgeschlagene Lesevorgänge verbrauchen kein Budget.

• Größenbegrenzungen. Notizen werden bei 50 KB gekürzt; Suchergebnisse und Aktualitätslisten sind begrenzt.

• Dot-Ordner werden übersprungen. .obsidian, .git und andere Dot-Ordner sind unsichtbar.

• Code ist öffentlich, Daten nicht. Das Repo enthält nur Servercode und ein fiktives Demo-Vault. Dein echtes Vault ist der Ordner, den du zur Laufzeit einbindest; er verlässt deinen Rechner nie.

FAQ

Verlassen meine Daten meinen Rechner? Nein. Der Server läuft lokal als Kindprozess deines MCP-Clients und liest Dateien von der Festplatte. Es gibt keinen Netzwerkcode darin.

Kann er meine Notizen ändern oder löschen? Nein. Es gibt kein Tool, das schreibt. Das ist eine Eigenschaft des Codes, keine Einstellung.

Was passiert, wenn das Modell das Budget erreicht? Der 6. Lesevorgang gibt einen Fehler zurück, der dem Modell sagt, es solle aus den Seiten synthetisieren, die es bereits hat. Ein neues Gespräch erhält ein frisches Budget.

Warum sprach die Demo-Antwort von „Alex Rivera“? Du verwendest das gebündelte fiktive Demo-Vault. Übergib deinen eigenen Vault-Pfad als erstes Argument.

Entwicklung

npm run build   # tsc -> dist/
npm test        # build + 15-check smoke test (spawns the real server over stdio)

Der Smoke-Test verwendet den eigenen Client des SDK gegen den kompilierten Server – echtes Protokoll, keine Mocks. Er prüft alle vier Tools, die Ressource, den Prompt, die Ablehnung von Pfad-Traversal und dass das Lesebudget den N+1-ten Lesevorgang verweigert. CI führt ihn unter Linux und Windows mit Node 20 und 22 aus.

Neugierig, warum es so gebaut ist? Siehe docs/design-notes.md – Transports, die drei MCP-Primitive, Schemas als Prompts und die Entscheidungen zu Sandbox und Budget.

Roadmap

• Remote-Variante (streamable HTTP), damit der Vault von gehosteten Clients erreichbar ist, mit Authentifizierung

• Optionale Eingrenzung pro Ordner (nur wiki/ bereitstellen, journal/ ausblenden)

Mitwirken

Issues und PRs sind willkommen. Behalte die Invarianten bei: keine Schreib-Tools, keine Netzwerkaufrufe, der Smoke-Test bleibt grün und ungeschwächt.

Lizenz

MIT · Änderungen in CHANGELOG.md