{
  "markdown": "# margins-mcp\n\n**Use your Claude Pro/Max subscription on your Obsidian vault.** No API key. No per-token costs. No embedding pipelines. Claude reads your notes and proposes updates; your subscription pays for inference; your files stay on your disk.\n\n`margins-mcp` is a small Node program that sits between Claude (Desktop or Code) and your Obsidian vault. When you chat with Claude, it reads your notes through `margins-mcp`. Your files stay local, Claude does the thinking, your existing subscription pays for it.\n\n## Which Margins are you?\n\nMargins works for six common starting points. `margins_start` auto-detects your state on the first call, so you don't have to classify yourself — but knowing which row you're on helps set expectations.\n\n| You... | Persona | First conversation |\n|---|---|---|\n| Obsidian, vault organized with wikilinks | **A1** | Q&A on your notes. `margins_start` then ask anything. |\n| Obsidian, vault is empty or new | **A2** | Ask Claude to scaffold daily-note + meeting templates. |\n| Obsidian, many files but few wikilinks | **A3** | Run `propose_wikilinks` on a page to surface connections you missed. |\n| No Obsidian, organized markdown | **B1** | Same as A1. Install Obsidian for the proposal-review UX. |\n| No Obsidian, empty | **B2** | Use `--starter-vault ~/Margins` to scaffold one. |\n| No Obsidian, messy folder | **B3** | Run `propose_wikilinks` on your busiest page. Install Obsidian to review proposals visually. |\n\n## Requirements\n\n- [Node.js 18 or newer](https://nodejs.org)\n- An Obsidian vault, or any folder with notes, PDFs, Office/OpenDocument files, email exports, EPUBs, or plain text\n- A Claude subscription: Pro ($20/mo), Max, or Claude Code\n\n## Install\n\nTwo commands:\n\n```sh\nnpm install -g margins-mcp\nmargins-mcp install\n```\n\nThe installer prompts for your vault path, detects Claude Desktop and Claude Code, writes the right config files, scaffolds `raw/` + `proposed/` + `.margins/` inside your vault if missing, and runs a verification probe. Restart Claude Desktop (`Cmd-Q` on macOS, not just close the window), or in Claude Code run `/mcp` to see Margins listed.\n\n### Don't have a vault yet?\n\nScaffold a Margins-shaped one:\n\n```sh\nmargins-mcp install --starter-vault ~/notes\n```\n\n### Finding your Obsidian vault path\n\nIf you already use Obsidian and don't know your vault's absolute path:\n\n- **In Obsidian:** right-click the vault name in the file tree → \"Reveal in Finder\" (macOS) or \"Show in Explorer\" (Windows). The path is in the title bar.\n- **macOS common paths:** `~/Documents/<VaultName>`, or `~/Library/CloudStorage/iCloudDrive/Obsidian/<VaultName>` if iCloud-synced.\n- **Linux common paths:** `~/Documents/<VaultName>`, or `~/.local/share/Obsidian/<VaultName>`.\n- **Windows common paths:** `%USERPROFILE%\\Documents\\<VaultName>`.\n\nPass it to the installer via `--vault /absolute/path` or answer the prompt.\n\n### Try-without-installing\n\n```sh\nnpx margins-mcp install --vault /path/to/vault\n```\n\nYou'll see a warning that npm may garbage-collect the npx cache and your configs would break weeks later. For real use, prefer `npm install -g` above. The npx path is fine for kicking the tires.\n\n### Manual install\n\nIf you'd rather edit config yourself, add this to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS; see [Anthropic docs](https://modelcontextprotocol.io/quickstart/user) for Windows/Linux paths):\n\n```json\n{\n  \"mcpServers\": {\n    \"margins\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/margins-mcp/bin/margins-mcp.js\"],\n      \"env\": { \"MARGINS_VAULT\": \"/absolute/path/to/your/vault\" }\n    }\n  }\n}\n```\n\n## Try it\n\nIn a new Claude conversation, ask:\n\n> Use margins to give me a summary of my recent notes.\n\nOr:\n\n> What pages support the claim that my project deadline is May 30th? Use margins to find them.\n\nOr:\n\n> I just dropped a spreadsheet into `raw/`. Compile it into a structured source page in my wiki.\n\nThe model can read your vault, propose new pages, propose edits to existing ones, and pull raw sources into structured wiki pages. `propose_compile_from_raw` accepts Markdown/plain text, PDFs, Word docs, spreadsheets, decks, email exports, EPUBs, OpenDocument files, RTF, HTML, CSV/TSV, JSON, YAML, and common text-ish formats. Every write stages to `proposed/` first; nothing lands without you accepting.\n\n## Tools\n\n### Context (call once per conversation)\n\n| Tool | Purpose |\n|------|---------|\n| `margins_start` | Vault stats + pending proposals + uningested raw files + recent preferences + the vault's `CLAUDE.md` if present. Claude's grounding for the whole conversation. |\n| `recall_preferences` | Read durable user preferences from `.margins/preferences.md` (filing conventions, naming patterns, prior corrections). Claude calls this before any propose. |\n\n### Read\n\n| Tool | Purpose |\n|------|---------|\n| `search_vault` | Full-text + filename search across the vault. |\n| `read_page` | Read one page by relative path. |\n| `list_recent` | Most recently modified pages. |\n| `get_backlinks` | Pages that wikilink to a target slug. |\n| `search` / `fetch` | ChatGPT Deep Research compatibility pair. |\n\n### Propose writes (staged — nothing lands until accepted)\n\n| Tool | Purpose |\n|------|---------|\n| `propose_page` | Stage a new page at `proposed/<path>`. |\n| `propose_edit` | Stage a string-replacement edit. `before` must appear exactly once. |\n| `append_to` | Stage an append. Creates the page if missing; stacks on pending proposals. |\n| `propose_compile_from_raw` | Turn a raw transcript, note, PDF, Word doc, spreadsheet, deck, email, EPUB, or other supported document in `raw/` into a structured source page. |\n| `list_proposals` | List pending proposals + overwrite-risk flag per entry. |\n| `resolve_proposal` | `action: \"accept\"` lands the proposal; `action: \"reject\"` discards it. |\n\n### Suggest (for A3 / B3 — vaults with many files but few links)\n\n| Tool | Purpose |\n|------|---------|\n| `propose_wikilinks` | Scan a page for entity-shaped phrases and propose wikilinks to other vault pages that share the same slug. The model then chains `propose_edit` calls to apply the ones it likes. |\n\n### Learn\n\n| Tool | Purpose |\n|------|---------|\n| `record_preference` | Append a durable rule to `.margins/preferences.md`. Claude calls this when the user corrects a proposal in a way that should apply next time (filing path, naming, summary length, etc.). |\n\n### How the proposal flow works\n\nEvery write tool stages to `proposed/<path>` inside your vault. Nothing touches the live tree until you (or an MCP client acting on your behalf) call `resolve_proposal` with `action: \"accept\"`. You can also inspect staged content (`ls proposed/`) and accept by moving files yourself.\n\nSequential edits stack: a second `propose_edit` on the same path reads from the pending proposal, not the vault.\n\n## Configuration\n\n| Env var | Default | Purpose |\n|---------|---------|---------|\n| `MARGINS_VAULT` | (required) | Absolute path to your Obsidian vault or Markdown folder. |\n| `MARGINS_INDEX_ROOTS` | auto-detected | Comma-separated subfolders to index. Auto-detection: `.obsidian/` present → index root; `wiki/` present → index `wiki/` only; neither → index root. |\n| `MARGINS_TELEMETRY` | (consent file) | Override telemetry: `on` or `off`. Default uses the consent decision made during install. |\n\n## What Margins is NOT\n\nTo keep scope crisp:\n\n- **Not an inference layer.** Your Claude subscription pays for that. Margins makes zero LLM calls.\n- **Not a web app.** The chat surface lives in Claude Desktop / Claude Code / claude.ai. Margins is plumbing.\n- **Not a cloud sync.** Local-first. Your files stay on your disk.\n- **Not a CRM integration.** Different product.\n- **Not API-key-based.** Subscription-passthrough is the whole point.\n\n## Privacy\n\n- Vault content never leaves your machine. Margins is a Node process that reads/writes files locally and exposes structured tools over stdio.\n- Anonymous telemetry (opt-in at install time) reports tool-call counts to help me prioritize what to build next. Sample event payload: `GET https://margins.goatcounter.com/count?p=/tool/search_vault`. No vault content, no file paths, no user identifier beyond the standard 24-hour rolling session token GoatCounter assigns. Disable per-session with `MARGINS_TELEMETRY=off`. Decision stored at `~/.margins/consent.json`.\n\n## Develop\n\n```sh\ngit clone https://github.com/cflorczyk9/Margins.git\ncd Margins\nnpm install\nnpm test\nMARGINS_VAULT=/path/to/test/vault npm start\n```\n\nThe compiler (`src/compiler/`) was originally vendored from an earlier Margins web app. The web app and its landing page live on the `legacy-webapp` branch in this repo. Re-vendor with `scripts/vendor-compiler.sh` if you ever need to pull updates back from there.\n\n## How Margins gets smarter over time\n\nTwo things compound:\n\n1. **Your vault's `CLAUDE.md`** is auto-loaded by `margins_start`. Drop vault-specific rules in there — filing conventions, voice, naming patterns — and Claude obeys them in every conversation. No copy-paste.\n2. **`.margins/preferences.md`** is a Margins-maintained file inside your vault. When you correct Claude (\"no, that should be in projects, not personal\"), Claude calls `record_preference` to remember the rule. Next conversation it reads them via `recall_preferences` before proposing writes. The file is plain Markdown — you can audit it, hand-edit it, delete sections that no longer apply.\n\nBoth files live in the vault, so they travel with it. Switch machines, switch hosts (Claude Desktop → Claude Code → ChatGPT once that lands), and your conventions follow.\n\n## Roadmap\n\n- v0.6: web onboarding at marginsmcp.com — pick a folder via File System Access, scaffold a vault, get the install command. Closes B2/B3 personas without requiring CLI fluency.\n- v0.6: `get_citations` (semantic embedding search, opt-in dep).\n- v0.6: OCR/image, legacy Office binary, and audio/video ingestion for `propose_compile_from_raw`.\n- v0.7: HTTP / Streamable transport for claude.ai web and ChatGPT custom connectors.\n- v0.7+: Obsidian community plugin alongside MCP, if signal supports it.\n- v0.8+: file watcher / auto-scaffold on drop into `raw/`.\n\n## License\n\nMIT\n",
  "bytes": 10188,
  "sha": "5b800c2e2ec78dd87973756cfcb56e96c2b30812a8a9388883d61bda3e86263a",
  "repo_slug": "cflorczyk9/margins",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_cflorczyk9_margins_48eb0e44/readme"
}