Provides direct access to an Obsidian vault via CouchDB and Obsidian LiveSync, enabling notes to be listed, read, written, searched, and updated with support for tags, frontmatter, and backlinks.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@obsidian-self-mcpSearch for notes about 'machine learning' and summarize the key points"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
obsidian-self-mcp
An MCP server and CLI that gives you direct access to your Obsidian vault through CouchDB — the same database that Obsidian LiveSync uses to sync your notes.
No Obsidian app required. Works on headless servers, in CI pipelines, from AI agents, or anywhere you can run Python.
How it works
If you use Obsidian LiveSync, your vault is already stored in CouchDB. This tool talks directly to that CouchDB instance — reading, writing, searching, and managing notes using the same document/chunk format that LiveSync uses. Changes sync back to Obsidian automatically.
Who this is for
Self-hosted LiveSync users who want programmatic vault access
Homelab operators running headless servers with no GUI
AI agent builders who need to give Claude, GPT, or other agents access to an Obsidian vault via MCP
Automation pipelines that read/write notes (changelogs, daily notes, project docs)
How this differs from Obsidian's official CLI
Obsidian has an official CLI that requires the Obsidian desktop app running locally and a Catalyst license. This project requires neither — just a CouchDB instance with LiveSync data.
Feature | Official CLI | obsidian-self-mcp |
Requires Obsidian app | Yes (must be running) | No |
Requires Catalyst license | Yes ($25+) | No (MIT, free) |
Read/write notes | Yes | Yes |
Search | Yes | Yes |
Frontmatter/properties | Yes | Yes |
Tags | Yes | Yes |
Backlinks | Yes (via app index) | Yes (content scanning) |
Templates | Yes | No (planned) |
Canvas | Yes | No |
Graph view | No | No |
Works headless/CI | No | Yes |
MCP server | No | Yes |
Transport | Local REST API | CouchDB (network) |
Requirements
Python 3.10+
A CouchDB instance with Obsidian LiveSync data
The database name, URL, and credentials
Installation
pip install obsidian-self-mcpOr install from source:
git clone https://github.com/suhasvemuri/obsidian-self-mcp.git
cd obsidian-self-mcp
pip install -e .Configuration
Set these environment variables:
export OBSIDIAN_COUCH_URL="http://your-couchdb-host:5984"
export OBSIDIAN_COUCH_USER="your-username"
export OBSIDIAN_COUCH_PASS="your-password"
export OBSIDIAN_COUCH_DB="obsidian-vault" # optional, defaults to "obsidian-vault"MCP Server Setup
Claude Desktop
Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"obsidian-self-mcp": {
"command": "python",
"args": ["-m", "obsidian_self_mcp.server"],
"env": {
"OBSIDIAN_COUCH_URL": "http://your-couchdb-host:5984",
"OBSIDIAN_COUCH_USER": "your-username",
"OBSIDIAN_COUCH_PASS": "your-password",
"OBSIDIAN_COUCH_DB": "obsidian-vault"
}
}
}
}Claude Code
Add to your Claude Code settings (.claude/settings.json or global):
{
"mcpServers": {
"obsidian-self-mcp": {
"command": "python",
"args": ["-m", "obsidian_self_mcp.server"],
"env": {
"OBSIDIAN_COUCH_URL": "http://your-couchdb-host:5984",
"OBSIDIAN_COUCH_USER": "your-username",
"OBSIDIAN_COUCH_PASS": "your-password",
"OBSIDIAN_COUCH_DB": "obsidian-vault"
}
}
}
}Available MCP Tools
Tool | Description |
| List notes with metadata, optionally filtered by folder |
| Read the full content of a note |
| Create or update a note |
| Search note content (case-insensitive) |
| Append content to an existing note |
| Delete a note and its chunks |
| List all folders with note counts |
| Read frontmatter properties from a note |
| Set/update frontmatter properties (JSON input) |
| List all tags in the vault with counts |
| Find notes containing a specific tag |
| Find notes that link to a given note |
| List wikilinks from a note |
CLI Usage
The obsidian command provides the same operations from the terminal:
# List notes
obsidian list
obsidian list "Dev Projects" -n 10
obsidian ls # alias
# Read a note
obsidian read "Notes/todo.md"
obsidian cat "Notes/todo.md" # alias
# Write a note
obsidian write "Notes/new.md" "# Hello"
obsidian write "Notes/new.md" -f local-file.md
echo "content" | obsidian write "Notes/new.md"
# Search
obsidian search "kubernetes" -d "Dev Projects" -n 5
obsidian grep "kubernetes" # alias
# Append to a note
obsidian append "Notes/log.md" "New entry"
# Delete a note
obsidian delete "Notes/old.md"
obsidian rm "Notes/old.md" -y # skip confirmation
# Frontmatter properties
obsidian props "Notes/todo.md" # read properties
obsidian props "Notes/todo.md" --set status=done # set a property
obsidian props "Notes/todo.md" --set 'tags=["a","b"]' status=active
# Tags
obsidian tags # list all tags with counts
obsidian tags "Dev Projects" # tags in a folder
obsidian tags --find "project" # find notes with a tag
# Backlinks and links
obsidian backlinks "Notes/todo.md" # notes linking to this note
obsidian links "Notes/todo.md" # outbound wikilinks from this note
# List folders
obsidian folders
obsidian tree # aliasHow LiveSync stores data
LiveSync splits each note into a parent document (metadata + ordered list of chunk IDs) and one or more chunk documents (the actual content). This tool handles all of that transparently — reads reassemble chunks in order, writes create proper chunk documents, and deletes clean up both the parent and all chunks.
Document IDs are lowercased vault paths. Paths starting with _ (like _Changelog/) get a / prefix since CouchDB reserves _-prefixed IDs.
License
MIT
This server cannot be installed
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.