Vault API — Obsidian MCP Plugin

Alpha v0.2.0 — work in progress. Expect breaking changes.

Connects your Obsidian vault to any AI that supports MCP — Claude Desktop, LM Studio, Ollama, Open WebUI, and others. No extra processes, no manual path configuration — the plugin is the MCP server, exposing a standard SSE endpoint on localhost.

Obsidian opens  →  plugin starts  →  MCP/SSE on 127.0.0.1:2768
AI client       →  connects       →  reads, writes, runs commands, sees images

Compatible clients

Client	How to connect
Claude Desktop	Settings → Vault API → Connect Claude (automatic)
LM Studio	Add MCP server → URL: http://127.0.0.1:2768/sse?key=<your-key>
Ollama / Open WebUI	Point any MCP-compatible front-end to the same SSE URL
Any MCP client	SSE transport at http://127.0.0.1:2768/sse with X-Api-Key header or ?key= query param

---

Features

Tool	Description
list_files	List vault files — filter by folder or extension
read_file	Read text files, view images inline, get binary data. Optional encoding:"base64" forces raw base64 for scripting.
write_file	Create or update a text file
write_binary	Create or overwrite any binary file (images, docx, pdf…) from base64 data
delete_file	Delete a file
search	Keyword search across filenames and note content
run_local_command	Run a shell command directly on your machine inside the vault folder

Image support

Images of any size are handled automatically:

File size	Max dimension	Format
≤ 4 MB	Original	As-is
4 MB – 20 MB	1024 px	JPEG 85 %
20 MB – 100 MB	800 px	JPEG 85 %
> 100 MB	512 px	JPEG 85 %

Images load directly from disk via Electron's Canvas API — no Node.js heap pressure. SVG files are returned as text (XML).

Binary file access

The /raw HTTP endpoint serves any vault file as raw bytes (authenticated), allowing scripts running inside Claude's execution sandbox to fetch() vault files directly — no base64 overhead.

---

Requirements

• Obsidian desktop (v1.0.0+) — plugin is desktop-only
• Any MCP-compatible AI client (Claude Desktop, LM Studio, Open WebUI, etc.)
• Node.js 18+ — only required for Claude Desktop (uses mcp-remote to bridge stdio → SSE). Not needed for clients with native SSE/HTTP MCP support.

---

Installation

1 — Copy plugin files

Download the latest obsidian-claude-mcp-vX.X.X.zip from Releases and extract it.

Copy the vault-api folder into your vault's plugin directory:

<your-vault>/
└── .obsidian/
    └── plugins/
        └── vault-api/        ← copy here
            ├── main.js
            ├── manifest.json
            └── styles.css

On Windows, enable View → Hidden items to see the .obsidian folder.

2 — Enable in Obsidian

Settings → Community plugins → disable Safe Mode → enable Vault API

You should see in the console (Ctrl+Shift+I):

[vault-api] MCP server started on port 2768

3 — Connect Claude Desktop

Settings → Vault API → Connect Claude

The plugin writes the MCP entry into claude_desktop_config.json automatically.

4 — Restart Claude Desktop

Fully quit Claude Desktop (Quit, not just close the window) and reopen it.

---

Plugin Settings

Setting	Description
Connect Claude	Auto-configures claude_desktop_config.json
Auto-start	Start the server when Obsidian loads (default: on)
Port	Port to listen on (default: 2768)
API Key	Auto-generated secret. Regenerate if compromised, then reconnect Claude
Restart / Stop	Manual server controls

The /health endpoint (http://127.0.0.1:2768/health) is publicly accessible without a key — useful for checking server status directly in the browser.

---

Upgrading

Replace main.js in your plugin folder with the one from the latest release, then reload the plugin in Obsidian (Settings → Community plugins → Vault API → toggle off → toggle on).

---

Building from Source

git clone https://github.com/Alexandre1116/Obsidian-vault-api
cd Obsidian-vault-api
npm install
npm run build    # outputs main.js

---

Changelog

v0.2.0

• New tool write_binary — create or overwrite any binary file (images, docx, pdf…) from base64 data
• New tool run_local_command — execute shell commands directly on the user's machine inside the vault directory, bypassing the cloud sandbox
• New /raw HTTP endpoint — serves vault files as raw bytes so scripts can fetch() them without base64 overhead
• read_file encoding:"base64" param — forces raw base64 text output for images, enabling scripting use cases
• search now skips binary/image files (faster, less noise)
• BINARY_EXTS guard avoids failed text-decode on pdf, docx, mp4, etc.
• Improved MIME type table (Office formats, audio, video)

v0.1.4

• Fixed server disconnect when reading large images — Canvas timeout reduced to 15 s, global 25 s tool safety wrapper added
• Tiered resize: files > 100 MB → 512 px, > 20 MB → 800 px, default → 1024 px
• JPEG quality 85 %

v0.1.3

• read_file on images now includes a text companion block with path, filename, ![[]] embed syntax

v0.1.2

• Fixed "Tool result could not be submitted" — SSE keep-alive pings every 15 s
• Fixed Check /health button — /health is now public

v0.1.1

• Images of any size supported via Electron Canvas API resize
• SVG returned as text; HTTP server timeouts disabled

v0.1.0

• Initial alpha release

---

License

This project is licensed under CC BY-NC-SA 4.0 — see LICENSE.

✅ Share	Copy and redistribute in any medium or format
✅ Adapt / Remix	Transform and build upon the material
✅ Free for personal use	Non-commercial use by anyone
❌ No commercial use	Companies, revenue-generating use not permitted
📝 Attribution required	Credit the original author (Alexandre Ramos)
🔄 ShareAlike	Remixes must use the same CC BY-NC-SA 4.0 license

---

Roadmap

• Obsidian Search API integration (tags, backlinks)
• Frontmatter / metadata tool
• Create/rename folders
• BRAT support for easy updates
• Settings UI improvements