Content
# obsidian-local-mcp
An MCP server that treats a specific directory on the local disk as an **Obsidian Vault**. It allows Claude (Desktop / Code) to **create, read, and modify** notes within the Vault and **read and create** folders. All new notes created by Claude are assigned Obsidian Properties (YAML frontmatter) in a fixed order:
```yaml
---
title:
aliases:
tags:
author:
date:
source:
type:
Service URL:
---
```
The Vault location and default author can be changed in the **local web settings page (GUI)**.
## Components
| Item | Description |
| --- | --- |
| MCP Server (`dist/index.js`) | Provides 7 tools (see below) |
| Settings Page (`npm run settings`) | Localhost web UI — Select Vault folder (native dialog) + default author |
| Skill (`skills/obsidian-vault`) | Claude Skill with Vault integration workflow rules |
### MCP Tools
- `create_note` — Create a new note (automatic YAML property assignment)
- `read_note` — Read note original/frontmatter/body
- `update_note` — Modify body (append/prepend/replace_body) and frontmatter
- `list_directory` — List folder contents (recursive option)
- `create_directory` — Create a folder
- `search_notes` — Search by file name/body/tags
- `get_vault_info` — Check Vault path, default author, and number of notes
## Installation
```bash
npm install
npm run build
```
## 1) Specify Vault (GUI)
```bash
npm run settings
```
The settings page opens in your browser. Select a folder using **‘Folder selection…’** to open the macOS folder dialog, choose the Vault folder (or enter it directly), input the default `author`, and click **Save**. The settings are saved to:
```
~/Library/Application Support/obsidian-local-mcp/config.json
```
> Note: If the settings file does not exist, the environment variable `OBSIDIAN_VAULT_PATH` is used as a fallback.
## 2) Register with Claude
### Claude Code (CLI)
```bash
claude mcp add obsidian -- node /ABSOLUTE/PATH/TO/obsidian-local-mcp/dist/index.js
```
Alternatively, create a `.mcp.json` file in the project root with the contents of `examples/mcp.json`.
Copy the skill to one of the following locations:
```bash
# Global usage
cp -r skills/obsidian-vault ~/.claude/skills/
# Or for a specific project only
cp -r skills/obsidian-vault /your/project/.claude/skills/
```
### Claude Desktop
Add the following to `claude_desktop_config.json` (see `examples/claude_desktop_config.json`):
```json
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/obsidian-local-mcp/dist/index.js"]
}
}
}
```
Settings file location: `~/Library/Application Support/Claude/claude_desktop_config.json`. Restart Claude Desktop after making changes. Activate the skill in Claude Desktop's Skills (Capabilities) settings by adding and enabling the `skills/obsidian-vault` folder.
## Operation Method / Safety
- All paths are **relative to the Vault root** and must be relative paths. Absolute paths and escaping with `..` are not allowed to prevent access to files outside the Vault.
- Frontmatter is always serialized in a fixed order of 8 keys (`aliases`/`tags` are lists, `date` is in Obsidian date format, and no quotes are used).
- Items starting with a dot (`.`) such as `.obsidian` and `.trash` are excluded from lists and searches.
## Verification (MCP Inspector)
```bash
npx @modelcontextprotocol/inspector node dist/index.js
```
You can verify the operation by calling `get_vault_info` → `create_note` → `read_note` → `list_directory` in the Inspector.
