Free · Open source · Margins MCP

Bring Claude toyour files.

Margins makes Claude smarter by turning your messy files into usable context. Drop in notes, transcripts, PDFs. Claude searches across them, cites sources, and compiles raw input into clean structured pages. Runs locally. No servers, no API key.

Get started → See it work

How it works

Three steps. You stay in the driver’s seat.

You decide what Claude can see, you decide what Claude writes, you ask later.

Step 1

Give it a folder.

Point Margins at one folder on your computer. Your Obsidian vault, a project directory, anything. Claude only ever sees what’s inside that folder. Nothing else on your machine.

Step 2

Drop your stuff in.

Drag in notes, writing, PDFs, meeting transcripts, anything you want Claude to know about. Ask Claude to compile it. Margins stages a clean source page in proposed/ for you to accept.

Step 3

Ask anything. Connect everything.

Claude searches the sources you’ve built, cites where each fact came from, and surfaces connections you didn’t make: a meeting that overlaps with another, a thread you forgot was open, a pattern across months of notes. New edits go in proposed/ for your review.

Step 1 of 3: Give it a folder.

Want the longer version? See the full walkthrough — folder layouts, the connection diagram, every tool Claude can call, and what the first month looks like.

Use cases

See Margins answer real questions across your files.

Seven scenarios across notes, transcripts, PDFs, code, decisions. Same move every time: Claude pulls the context, follows the thread, and finds what you'd miss.

Coffee — Casey Tran
Recorded conversation. Real tools, real flow. Your vault stays on your disk.
Demo transcript (text version)

Compare

How Margins compares to other AI tools for your files.

There are a few other ways to point an AI at your notes. Here's where they overlap with Margins and where Margins is more specific.

Capability
Margins MCP
Filesystem MCP
Smart Connections
NotebookLM
Finds connections across files (wikilinks, backlinks, cross-document synthesis)
semantic, no graph
Q&A only, no graph
Compiles raw inputs into structured pages
Write capability
propose-only (you review)
direct (no review step)
read-only
read-only
Free to run
uses your Claude subscription
uses your Claude subscription
BYOK OpenAI
Google account
Files stay on your disk
uploaded to Google
Works in Claude Desktop and Claude Code
in-Obsidian only

Margins MCP

  • Finds connections across files
  • Compiles raw inputs into structured pages
  • Write capabilitypropose-only (you review)
  • Free to runuses your Claude subscription
  • Files stay on your disk
  • Works in Claude Desktop and Claude Code

Filesystem MCP

  • Finds connections across files
  • Compiles raw inputs into structured pages
  • Write capabilitydirect (no review step)
  • Free to runuses your Claude subscription
  • Files stay on your disk
  • Works in Claude Desktop and Claude Code

Smart Connections

  • Finds connections across filessemantic, no graph
  • Compiles raw inputs into structured pages
  • Write capabilityread-only
  • Free to runBYOK OpenAI
  • Files stay on your disk
  • Works in Claude Desktop and Claude Codein-Obsidian only

NotebookLM

  • Finds connections across filesQ&A only, no graph
  • Compiles raw inputs into structured pages
  • Write capabilityread-only
  • Free to runGoogle account
  • Files stay on your diskuploaded to Google
  • Works in Claude Desktop and Claude Code

FAQ

Common questions about Margins.

What does Margins MCP do?

Margins MCP is a local-first MCP server. It gives Claude Desktop and Claude Code a small set of tools: search your files, read individual pages by path, follow wikilinks and backlinks, and stage write proposals to a proposed/ folder you review before accepting. The tools run on your machine against a folder you point them at.

Do I need an API key?

No. Margins uses your existing Claude Pro or Max subscription. There are no per-token costs and no separate API account. If you already pay Anthropic, you don't pay anything else to use Margins.

Does it work with Claude Desktop and Claude Code?

Yes. The installer writes the MCP config for both. It does not work with the claude.ai web interface yet; the browser version doesn't support MCP connectors.

Where do my files live? What can Claude actually see?

Claude can only see the one folder you point Margins at. Not your Documents, not your Desktop, not your whole machine. Just that folder. If you don't drop a file into it, Claude doesn't know it exists.

Your files stay on your disk. Margins runs locally; no content is sent to any server controlled by Margins. The only data leaving your computer is whatever Claude needs to answer your prompt, which goes directly from your machine to Anthropic under your existing subscription. Margins is not a hosted service.

What kinds of files does it work with?

Any folder with Markdown, plain text, or PDFs in it. Margins doesn't care if it's a notes app's vault, an iCloud Drive folder, a project repo, or a directory of meeting transcripts. Obsidian works particularly well because Margins understands wikilinks and backlinks, but it isn't required.

If you point Margins at a folder that doesn't have a structure yet, the installer can scaffold a starter: raw/ for inputs, proposed/ for staged writes, and a CLAUDE.md operator manual.

Can Claude edit my notes directly?

No. Claude can only propose writes. Every proposed edit is staged in a proposed/ folder inside your vault. You review the file, then move it into place to accept (or delete it to reject). Your real notes are never modified without your action.

How is this different from the Filesystem MCP?

Filesystem MCP gives Claude raw file access to any folder, with no review step. Margins is vault-aware: it understands wikilinks and backlinks, has a propose-then-accept safety model, includes tools that compile raw transcripts into structured source pages, and exposes vault context on first use so Claude knows what it's looking at.

Filesystem MCP is more general; Margins is more specific to how knowledge-work vaults are actually shaped.

Is it open source? How much does it cost?

Yes, MIT-licensed. The source is on GitHub and the npm package is margins-mcp. Margins itself is free. The only ongoing cost is your existing Claude subscription, which you would have anyway.

Get started

Install Margins.

You saw it. Now run it on your files.

Claude Desktop

Install for Claude Desktop.

Double-click. Pick a folder. Ask Claude.

Margins shows up in your Connector list with its logo.

Download for Claude Desktop
~28 MB · macOS & Windows · MIT
Claude Code / CLI

Install via npm.

  • $ npm install -g margins-mcp
  • $ margins-mcp install --vault /absolute/path/to/your/files

The installer writes configs for Claude Desktop and Claude Code, scaffolds raw/, proposed/, and .margins in your folder, and verifies. To update later: margins-mcp install --update.

Path 1 of 2
Path 1 of 2: Claude Desktop.

Don't have a folder of files yet?

Margins can scaffold a starter for you. wiki/, raw/, proposed/, plus a CLAUDE.md operator manual.