🧠 Second Brain MCP

An MCP (Model Context Protocol) server that turns your Obsidian vault into an AI-queryable second brain.

It combines:

• KuzuDB — an embedded graph database to store notes, tags, and [[wikilink]] relationships
• ChromaDB — a local vector database for semantic search over note contents
• Watchdog — a live file watcher that auto-indexes notes as you write/edit/delete them

✨ Features

🚀 Setup

1. Clone the repository

git clone https://github.com/your-username/Second-Brain-MCP.git
cd Second-Brain-MCP

2. Create and activate a virtual environment

python -m venv .venv
# Windows
.venv\Scripts\activate
# macOS/Linux
source .venv/bin/activate

3. Install dependencies

pip install -r requirements.txt

4. Set your vault path

Set the VAULT_PATH environment variable to the absolute path of your Obsidian vault:

# Windows (PowerShell)
$env:VAULT_PATH = "C:\Users\YourName\Documents\MyVault"

# macOS/Linux
export VAULT_PATH="/Users/YourName/Documents/MyVault"

If VAULT_PATH is not set, the server defaults to a local ./vault/ folder.

5. Run the server

python main.py

On first run, the server performs an initial sync — crawling and indexing all .md files in the vault. Subsequent runs are faster as the databases persist in the .db_data/ folder.

🔌 Connecting to an MCP Client

This server uses FastMCP. To connect it to Claude Desktop or any MCP-compatible client, add it to your MCP config:

{
  "mcpServers": {
    "second-brain": {
      "command": "python",
      "args": ["C:/path/to/Second-Brain-MCP/main.py"],
      "env": {
        "VAULT_PATH": "C:/path/to/your/ObsidianVault"
      }
    }
  }
}

📁 Project Structure

Second-Brain-MCP/
├── main.py          # MCP server entry point & all tool definitions
├── graph.py         # KuzuDB graph database wrapper
├── vector.py        # ChromaDB vector database wrapper
├── parser.py        # Obsidian markdown & frontmatter parser
├── watcher.py       # Live vault file watcher (watchdog)
├── requirements.txt # Python dependencies
└── .db_data/        # Auto-created: persisted KuzuDB & ChromaDB data

⚙️ Dependencies

📝 Notes

• All databases are stored locally in .db_data/ — no cloud services required.
• The embedding model (all-MiniLM-L6-v2) is downloaded once and cached by sentence-transformers.
• The NLI model for surface_contradictions (cross-encoder/nli-MiniLM2-L6-H768) is optional; if unavailable, a lexical negation fallback is used.
• Notes are matched by filename (without .md) as their title, unless a title: field is set in the YAML frontmatter.

📄 License

MIT