Content
# Obsidian MCP
A local [Model Context Protocol](https://modelcontextprotocol.io/) server that lets MCP-compatible assistants safely read and modify explicitly configured Obsidian vaults.
Version 2 supports both MCP `2026-07-28` and 2025-era clients by default, and requires Node.js 22 or newer. It works directly with Markdown files, so Obsidian does not need to be open. Legacy protocol and v1 positional-path compatibility are deprecated and print exact migration instructions to stderr.
> [!IMPORTANT]
> MCP clients can invoke destructive tools. Back up important vaults, review client permission prompts, and use revision preconditions for concurrently edited notes.
## Quick start
Node.js 22 or newer is required:
```bash
node --version # v22 or newer
```
Run with `npx` without installing the package globally. Pinning the major version receives compatible 2.x updates without automatically crossing a future major version:
```bash
npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/vault
```
Configure an MCP client to launch the same command over stdio:
```json
{
"mcpServers": {
"obsidian": {
"command": "npx",
"args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/vault"]
}
}
}
```
Alternatively, install the package globally and use `"command": "obsidian-mcp"` with the same arguments beginning at `"serve"`:
```bash
npm install -g obsidian-mcp@2
```
Each vault must already contain an `.obsidian` directory and must be configured using an absolute path.
Both protocol eras are served from the same tool definitions. After confirming that your MCP client negotiates `2026-07-28`, you may opt into modern-only mode by adding `"--legacy", "reject"` to `args`.
Vault ids use lowercase letters, digits, `_`, and `-`, must begin with a letter, and are the values assistants pass to tools. Up to ten vaults may be configured. Repeat `--vault` to expose more than one vault:
```bash
obsidian-mcp serve \
--vault work=/Users/me/Documents/WorkVault \
--vault personal=/Users/me/Documents/PersonalVault
```
Network, removable, hidden, and synced locations are allowed because an explicit `--vault` is treated as authorization; the same containment protections apply to every location.
## Design principles
- Vault access is explicitly allowlisted at process startup.
- Every tool path is vault-relative, segment-checked, and blocked from symlinks and reserved state.
- File mutations are journaled, conflict-checked, atomically replaced, and rolled back as one transaction.
- The server never listens on a network interface or sends telemetry.
- stdout is reserved exclusively for MCP messages; structured diagnostics go to stderr.
- Results are bounded, paginated where appropriate, and available as both text and structured content.
## Tools
| Tool | Purpose |
| --------------------------- | ----------------------------------------------------------------------------- |
| `obsidian_list_vaults` | List configured vault ids without exposing host paths. |
| `obsidian_read_note` | Read a bounded page of a note and return its SHA-256 `etag`. |
| `obsidian_create_note` | Atomically create a note without overwriting. |
| `obsidian_edit_note` | Append, prepend, or replace exact note content. |
| `obsidian_delete_note` | Move a note to MCP trash or permanently delete it with explicit confirmation. |
| `obsidian_move_note` | Move or rename a note and update unambiguous backlinks transactionally. |
| `obsidian_create_directory` | Transactionally create a directory inside a vault. |
| `obsidian_search_vault` | Search content, filenames, or tags with bounded cursor pagination. |
| `obsidian_add_tags` | Add tags to one or more notes atomically. |
| `obsidian_remove_tags` | Remove exact, nested, or wildcard-selected tags atomically. |
| `obsidian_rename_tag` | Rename a tag across the vault atomically. |
| `obsidian_manage_tags` | Unified add/remove tag workflow using the same implementation. |
All schemas are strict JSON Schema 2020-12 contracts generated from Zod. Mutating results include a transaction id; tool failures return `isError: true` with an actionable error code.
### Reading and concurrency
`obsidian_read_note` returns an `etag`. Pass it as `if_match` to edit, move, or delete when avoiding lost updates matters. Batch tag operations accept an `expected_etags` map. A changed note returns `REVISION_CONFLICT` rather than being overwritten.
Large notes are paginated using an opaque cursor bound to the path and `etag`. Search uses an opaque cursor bound to the query and options. Tool text responses are capped at 25,000 characters.
### Deletion and recovery
Trash is the default. Deleted note bytes and metadata are stored separately under `.obsidian-mcp/trash`; metadata is never injected into the note. Permanent deletion requires `confirm_path` to exactly match the canonical relative path.
Transactions and recovery snapshots live in `.obsidian-mcp/transactions`. Completed data is retained for 30 days and pruned oldest-first above 1 GiB by default:
```bash
obsidian-mcp serve --vault work=/path \
--recovery-days 14 \
--recovery-max-bytes 536870912
```
Inspect or restore a completed transaction while the MCP server is stopped:
```bash
obsidian-mcp recovery list --vault work=/path
obsidian-mcp recovery restore --vault work=/path --id <transaction-id>
```
Recovery refuses to overwrite content changed since the selected transaction. Permanent deletion snapshots are purged after commit and cannot be restored.
## Path and filesystem safety
The server:
- canonicalizes configured vault roots and rejects duplicate or nested roots;
- rejects absolute, UNC, Windows-drive, NUL, backslash, empty, and dot-segment tool paths;
- reserves `.obsidian`, `.obsidian-mcp`, `.git`, `.backup`, and `.trash` from tool access;
- checks existing targets and the nearest existing ancestor for new targets;
- rejects symlinks, junctions, and reparse-point paths, and skips them during scans;
- performs no shell execution for filesystem validation;
- strictly decodes UTF-8 and does not silently replace invalid bytes.
The process needs read and write access to each configured vault. `obsidian-mcp doctor --vault id=/path` validates startup readiness and recovery state.
## Link and tag behavior
Moves recognize Obsidian Wikilinks, embeds, Markdown links, aliases, URL-encoded destinations, headings, and block anchors. A link is rewritten only when it resolves unambiguously to the source note; ambiguous links are reported and left unchanged. Deletion preserves backlinks unless `backlink_action: "mark_broken"` is requested.
Tags follow Obsidian's case-insensitive rules and support Unicode, emoji, `_`, `-`, `/`, and nested tags. Frontmatter tags are written as YAML lists. Inline tag processing ignores fenced/inline code and HTML comments. Wildcards use a bounded matcher rather than regular expressions.
## Development
```bash
npm ci
npm run typecheck
npm test
npm run build
npm run ci
```
Each tool owns a typed definition under `src/tools/<tool>/index.ts`; the small registry in `src/tools/index.ts` applies shared MCP registration and response behavior. Filesystem, transaction, Markdown, link, and search behavior live in reusable utilities. A new tool must use `VaultFs` for every path, `TransactionManager` for mutations, strict input/output schemas, structured results, annotations, and security/integration tests.
See [MIGRATING.md](MIGRATING.md) for the 1.x migration and [SECURITY.md](SECURITY.md) for vulnerability reporting.
Startup errors and compatibility warnings are written only to stderr with a stable code, the detected problem, an exact fix, a verification step, and a link to the matching migration section. If the server does not appear, find the code in the MCP client logs and use the [diagnostic reference](MIGRATING.md#diagnostic-reference).
## License
MIT
Connection Info
You Might Also Like
No recommendations available