# Taproot

**Your notes. _Your AI's memory._**

MCP server that connects any AI client — Claude, ChatGPT, Cursor, Windsurf — to your Obsidian vault. Save anything from anywhere, ask questions across your notes, keep the knowledge base your AI reads from.

## 30-Second Setup

### Claude Desktop

1. Open config: **Mac** `~/Library/Application Support/Claude/claude_desktop_config.json` | **Windows** `%APPDATA%\Claude\claude_desktop_config.json`
2. Add Taproot to the `mcpServers` object:

```json
{
  "mcpServers": {
    "taproot": {
      "command": "npx",
      "args": ["-y", "synapse-obsidian", "/path/to/your/obsidian-vault"]
    }
  }
}
```

3. Restart Claude Desktop. Taproot tools appear automatically.

### Claude Code

Add to `.claude/.mcp.json` in your home directory:

```json
{
  "mcpServers": {
    "taproot": {
      "command": "npx",
      "args": ["-y", "synapse-obsidian", "/path/to/your/vault"]
    }
  }
}
```

### Claude.ai / ChatGPT / Any remote AI

Run Taproot locally and expose it with a free tunnel:

```bash
# Terminal 1: Start Taproot
npx synapse-obsidian /path/to/vault --http --port 3777

# Terminal 2: Expose it (free, no account needed)
npx cloudflared tunnel --url http://localhost:3777
```

Copy the tunnel URL. Add `https://your-tunnel-url.trycloudflare.com/mcp` as a custom MCP integration in your AI client.

## Getting Started

Once connected, say:

> **"Help me get started with Taproot"**

Taproot scans your vault and gives you three options:

- **Use my existing vault** — Detects your folder structure, wikilinks, naming conventions. Nothing moved or overwritten. Taproot adapts to you.
- **Set up a knowledge base** — Creates organized folders: `sources/` for raw content, `notes/` for compiled knowledge, `outputs/` for query results. Best for a focused research topic.
- **Custom** — You tell Taproot how you want things organized.

It also asks what you'll use the vault for (research, business, academic, life OS) so it can tailor the experience.

## What You Can Do

### Save anything, from anywhere

> "Save this article: https://example.com/interesting-post"

Fetches the page, converts to markdown, saves to your vault. Works from your phone.

### Ask questions across your notes

> "What do my notes say about pricing strategy?"

Searches your vault, reads relevant files, synthesizes a cited answer.

### Build a compounding wiki

> "Process all new articles in my vault"

Turns raw sources into summaries, concept pages, entity pages — all cross-linked with wikilinks. Every answer feeds back into the knowledge base.

### Health check your notes

> "Run a health check on my vault"

Finds broken links, orphan pages, missing frontmatter, stale content. Fixes what it can.

## All Tools

| Tool                | What it does                                                   |
| ------------------- | -------------------------------------------------------------- |
| `taproot_plant`     | Onboarding — scans vault, presents options, configures Taproot |
| `taproot_till`      | Saves your vault preferences                                   |
| `taproot_seed`      | Save content from a URL or pasted text                         |
| `taproot_status`    | Full vault overview with suggested actions                     |
| `taproot_water`     | Process a source into organized pages                          |
| `taproot_cultivate` | Find and process all unprocessed sources                       |
| `taproot_harvest`   | Research a question across your knowledge base                 |
| `taproot_prune`     | Health-check for broken links, orphans, gaps                   |
| `taproot_sow`       | Scaffold a new knowledge base from scratch                     |
| `garden_read`       | Read any file                                                  |
| `garden_plant`      | Create or update any file                                      |
| `garden_survey`     | List files in vault or subdirectory                            |
| `garden_forage`     | Full-text search                                               |
| `garden_measure`    | File counts and structure                                      |
| `garden_tag`        | Read YAML metadata from a file                                 |

## How It Works

Taproot is an [MCP server](https://modelcontextprotocol.io) — an open protocol for connecting AI to tools and data. It gives your AI read/write access to your vault (and nothing else — sandboxed to the vault directory).

- **Stdio** (default) — For desktop AI apps (Claude Desktop, etc.)
- **HTTP** (`--http`) — For browser-based AI (Claude.ai, ChatGPT, etc.) behind Tailscale or another tunnel

Your vault is just a folder of markdown files. Taproot doesn't need Obsidian to be running — it works with any folder.

## Requirements

- [Node.js](https://nodejs.org) 18+ (check with `node -v`)
- An Obsidian vault or any folder of markdown files
- Any MCP-compatible AI client

## License

MIT — [Taproot](https://taproothq.com)