Margins MCP server

margins-mcp

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.

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.

Which Margins are you?

Margins 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.

Requirements

• Node.js 18 or newer
• An Obsidian vault, or any folder with notes, PDFs, Office/OpenDocument files, email exports, EPUBs, or plain text
• A Claude subscription: Pro ($20/mo), Max, or Claude Code

Install

Two commands:

npm install -g margins-mcp
margins-mcp install

The 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.

Don't have a vault yet?

Scaffold a Margins-shaped one:

margins-mcp install --starter-vault ~/notes

Finding your Obsidian vault path

If you already use Obsidian and don't know your vault's absolute path:

• 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.
• macOS common paths: ~/Documents/, or ~/Library/CloudStorage/iCloudDrive/Obsidian/ if iCloud-synced.
• Linux common paths: ~/Documents/, or ~/.local/share/Obsidian/.
• Windows common paths: %USERPROFILE%\Documents\.

Pass it to the installer via --vault /absolute/path or answer the prompt.

Try-without-installing

npx margins-mcp install --vault /path/to/vault

You'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.

Manual install

If you'd rather edit config yourself, add this to ~/Library/Application Support/Claude/claudedesktopconfig.json (macOS; see Anthropic docs for Windows/Linux paths):

{
  "mcpServers": {
    "margins": {
      "command": "node",
      "args": ["/absolute/path/to/margins-mcp/bin/margins-mcp.js"],
      "env": { "MARGINS_VAULT": "/absolute/path/to/your/vault" }
    }
  }
}

Try it

In a new Claude conversation, ask:

Use margins to give me a summary of my recent notes.

Or:

What pages support the claim that my project deadline is May 30th? Use margins to find them.

Or:

I just dropped a spreadsheet into raw/. Compile it into a structured source page in my wiki.

Shortened. The full README is on GitHub.