Skip to content
Back to search

obsidian-mcp

A simple MCP server for Obsidian

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stevenstavrakis--obsidian-mcp/badge.svg)](/listings/stevenstavrakis--obsidian-mcp)

HTML

<a href="/listings/stevenstavrakis--obsidian-mcp"><img src="/api/listings/stevenstavrakis--obsidian-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Node.js 22 or newer is required:

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:

npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/vault

Configure an MCP client to launch the same command over stdio:

{
  "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"`:

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:

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.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 150 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Obsidian MCP
  2. A local [Model Context Protocol](https://modelcontextprotocol.io/) server that lets MCP-compatible assistants safely read and modify explicitly configured Obsidian vaults.
  3. 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.
  4. > [!IMPORTANT]
  5. > MCP clients can invoke destructive tools. Back up important vaults, review client permission prompts, and use revision preconditions for concurrently edited notes.
  6. ## Quick start
  7. Node.js 22 or newer is required:
  8. ```bash
  9. node --version # v22 or newer
  10. ```
  11. Run with `npx` without installing the package globally. Pinning the major version receives compatible 2.x updates without automatically crossing a future major version:
  12. ```bash
  13. npx -y obsidian-mcp@2 serve --vault notes=/absolute/path/to/vault
  14. ```
  15. Configure an MCP client to launch the same command over stdio:
  16. ```json
  17. {
  18. "mcpServers": {
  19. "obsidian": {
  20. "command": "npx",
  21. "args": ["-y", "obsidian-mcp@2", "serve", "--vault", "notes=/absolute/path/to/vault"]
  22. }
  23. }
  24. }
  25. ```
  26. Alternatively, install the package globally and use `"command": "obsidian-mcp"` with the same arguments beginning at `"serve"`:
  27. ```bash
  28. npm install -g obsidian-mcp@2
  29. ```
  30. Each vault must already contain an `.obsidian` directory and must be configured using an absolute path.
  31. 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`.
  32. 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:
  33. ```bash
  34. obsidian-mcp serve \
  35. --vault work=/Users/me/Documents/WorkVault \
  36. --vault personal=/Users/me/Documents/PersonalVault
  37. ```
  38. Network, removable, hidden, and synced locations are allowed because an explicit `--vault` is treated as authorization; the same containment protections apply to every location.
  39. ## Design principles
  40. - Vault access is explicitly allowlisted at process startup.
  41. - Every tool path is vault-relative, segment-checked, and blocked from symlinks and reserved state.
  42. - File mutations are journaled, conflict-checked, atomically replaced, and rolled back as one transaction.
  43. - The server never listens on a network interface or sends telemetry.
  44. - stdout is reserved exclusively for MCP messages; structured diagnostics go to stderr.
  45. - Results are bounded, paginated where appropriate, and available as both text and structured content.
  46. ## Tools
  47. | Tool | Purpose |
  48. | --------------------------- | ----------------------------------------------------------------------------- |
  49. | `obsidian_list_vaults` | List configured vault ids without exposing host paths. |
  50. | `obsidian_read_note` | Read a bounded page of a note and return its SHA-256 `etag`. |
  51. | `obsidian_create_note` | Atomically create a note without overwriting. |
  52. | `obsidian_edit_note` | Append, prepend, or replace exact note content. |
  53. | `obsidian_delete_note` | Move a note to MCP trash or permanently delete it with explicit confirmation. |
  54. | `obsidian_move_note` | Move or rename a note and update unambiguous backlinks transactionally. |
  55. | `obsidian_create_directory` | Transactionally create a directory inside a vault. |
  56. | `obsidian_search_vault` | Search content, filenames, or tags with bounded cursor pagination. |
  57. | `obsidian_add_tags` | Add tags to one or more notes atomically. |
  58. | `obsidian_remove_tags` | Remove exact, nested, or wildcard-selected tags atomically. |
  59. | `obsidian_rename_tag` | Rename a tag across the vault atomically. |
  60. | `obsidian_manage_tags` | Unified add/remove tag workflow using the same implementation. |
  61. 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.
  62. ### Reading and concurrency
  63. `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.
  64. 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.
  65. ### Deletion and recovery
  66. 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.
  67. 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:
  68. ```bash
  69. obsidian-mcp serve --vault work=/path \
  70. --recovery-days 14 \
  71. --recovery-max-bytes 536870912
  72. ```
  73. Inspect or restore a completed transaction while the MCP server is stopped:
  74. ```bash
  75. obsidian-mcp recovery list --vault work=/path
  76. obsidian-mcp recovery restore --vault work=/path --id <transaction-id>
  77. ```
  78. Recovery refuses to overwrite content changed since the selected transaction. Permanent deletion snapshots are purged after commit and cannot be restored.
  79. ## Path and filesystem safety
  80. The server:
  81. - canonicalizes configured vault roots and rejects duplicate or nested roots;
  82. - rejects absolute, UNC, Windows-drive, NUL, backslash, empty, and dot-segment tool paths;
  83. - reserves `.obsidian`, `.obsidian-mcp`, `.git`, `.backup`, and `.trash` from tool access;
  84. - checks existing targets and the nearest existing ancestor for new targets;
  85. - rejects symlinks, junctions, and reparse-point paths, and skips them during scans;
  86. - performs no shell execution for filesystem validation;
  87. - strictly decodes UTF-8 and does not silently replace invalid bytes.
  88. The process needs read and write access to each configured vault. `obsidian-mcp doctor --vault id=/path` validates startup readiness and recovery state.
  89. ## Link and tag behavior
  90. 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.
  91. 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.
  92. ## Development
  93. ```bash
  94. npm ci
  95. npm run typecheck
  96. npm test
  97. npm run build
  98. npm run ci
  99. ```
  100. 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.
  101. See [MIGRATING.md](MIGRATING.md) for the 1.x migration and [SECURITY.md](SECURITY.md) for vulnerability reporting.
  102. 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).
  103. ## License
  104. MIT

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.