README.md
Manage notes and vault data in Obsidian using AI agents.
obsidian-ts-mcp
A Model Context Protocol (MCP) server that wraps the official Obsidian CLI, letting AI agents in VS Code (and any other MCP client) read, write, search, and manage notes inside an Obsidian vault.
Prerequisites
| Requirement | Minimum version |
|---|---|
| Node.js | 18 |
| Obsidian desktop app | 1.12 (with CLI enabled) |
| Obsidian Catalyst licence | Required for CLI access |
The Obsidian desktop app must be running when the MCP server is in use.
The obsidian binary must be available on your PATH.
Installation
git clone https://github.com/dickiedyce/obsidian-ts-mcp.git
cd obsidian-ts-mcp
npm install
npm run build
Configuration
VS Code (user-level MCP)
Add the following to your VS Code MCP configuration:
| OS | Path |
|---|---|
| macOS | ~/Library/Application Support/Code/User/mcp.json |
| Linux | ~/.config/Code/User/mcp.json |
| Windows | %APPDATA%\Code\User\mcp.json |
{
"servers": {
"obsidian": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
"env": {
"OBSIDIAN_VAULT": "My Vault"
}
}
}
}
Claude Desktop
Add to claude_desktop_config.json
(~/Library/Application Support/Claude/claude_desktop_config.json on macOS,
%APPDATA%\Claude\claude_desktop_config.json on Windows):
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"],
"env": {
"OBSIDIAN_VAULT": "My Vault"
}
}
}
}
Set OBSIDIAN_VAULT to the name of the vault you want to target. The name
must match exactly what Obsidian shows in the vault switcher.
Environment variables
| Variable | Description |
|---|---|
OBSIDIAN_VAULT |
Default vault name appended to every CLI call. |
OBSIDIAN_VAULT_PATH |
Absolute filesystem path to the vault root. Used by direct filesystem operations; if unset, the path is resolved via the CLI. |
Available tools
The server exposes 37 tools organised into eleven groups.
Core -- note management
| Tool | Description |
|---|---|
create_note |
Create a new note, optionally from a template. Supports a path parameter for exact placement in subdirectories. |
read_note |
Read the full markdown contents of a note. |
append_to_note |
Append content to the end of a note. |
prepend_to_note |
Prepend content after the frontmatter of a note. |
search_vault |
Full-text search with Obsidian query syntax. |
daily_note |
Get or create today's daily note. |
daily_append |
Append content to today's daily note. |
Discovery and context
| Tool | Description |
|---|---|
get_vault_info |
Vault name, path, file/folder counts, size. |
list_files |
List files, optionally filtered by folder or extension. |
get_tags |
List all tags with occurrence counts. |
get_backlinks |
Find notes that link to a given note. |
get_outline |
Heading structure of a note. |
Properties and metadata
| Tool | Description |
|---|---|
set_property |
Set a frontmatter property on a note. |
read_property |
Read a frontmatter property value. |
Tasks
| Tool | Description |
|---|---|
list_tasks |
List tasks, with filters for status, file, or daily note. |
toggle_task |
Toggle a task checkbox on or off. |
Daily notes (extended)
| Tool | Description |
|---|---|
daily_read |
Read the contents of today's daily no |
Tools (16)
create_noteCreate a new note, optionally from a template.read_noteRead the full markdown contents of a note.append_to_noteAppend content to the end of a note.prepend_to_notePrepend content after the frontmatter of a note.search_vaultFull-text search with Obsidian query syntax.daily_noteGet or create today's daily note.daily_appendAppend content to today's daily note.get_vault_infoVault name, path, file/folder counts, size.list_filesList files, optionally filtered by folder or extension.get_tagsList all tags with occurrence counts.get_backlinksFind notes that link to a given note.get_outlineHeading structure of a note.set_propertySet a frontmatter property on a note.read_propertyRead a frontmatter property value.list_tasksList tasks, with filters for status, file, or daily note.toggle_taskToggle a task checkbox on or off.Environment Variables
OBSIDIAN_VAULTrequiredDefault vault name appended to every CLI call.OBSIDIAN_VAULT_PATHAbsolute filesystem path to the vault root.Configuration
claude_desktop_config.json
{"mcpServers": {"obsidian": {"command": "node", "args": ["/absolute/path/to/obsidian-ts-mcp/dist/server.js"], "env": {"OBSIDIAN_VAULT": "My Vault"}}}}Try it
→Search my vault for all notes tagged with #project-alpha and summarize their content.
→Create a new daily note entry with a summary of my completed tasks for today.
→List all files in my 'Meetings' folder and provide an outline for the most recent one.
→Find all notes that link to my 'Ideas' note and update their status property to 'reviewed'.