Skip to main content
Glama

ObsidianConnector

Local, Windows-first MCP access to explicitly registered Obsidian vaults. The server uses STDIO only and exposes Markdown note operations to Codex and ChatGPT Desktop without granting arbitrary filesystem access.

Requirements

  • Node.js 20 or newer

  • npm

  • An Obsidian vault directory, if you want to register an existing vault

The first version intentionally excludes HTTP, OAuth, tunnels, databases, web hosting, custom UI, semantic search, embeddings, synchronization, and attachment management.

Related MCP server: Obsidian MCP Server

Windows PowerShell setup

cd 'C:\path\to\ObsidianConnector'
npm install
Copy-Item .env.example .env
New-Item -ItemType Directory -Force config | Out-Null
@'
{
  "vaults": {
    "personal": {
      "path": "C:\\Users\\USERNAME\\Documents\\Obsidian\\Personal",
      "readOnly": false,
      "dailyNotes": { "directory": "Daily", "dateFormat": "YYYY-MM-DD" }
    }
  }
}
'@ | Set-Content config\vaults.json
npm run typecheck
npm test
npm run build

The configuration path defaults to config/vaults.json. The local .env sets OBSIDIAN_VAULT_ROOT=G:\\My Drive\\.obsidian; only registered vaults beneath that directory are returned by list_vaults, and new vaults are created there. Set $env:OBSIDIAN_MCP_CONFIG or $env:OBSIDIAN_VAULT_ROOT to override these values for a local run. Use register_vault for an existing vault elsewhere, but it will remain hidden from list_vaults unless it is under the configured root.

WSL/Linux setup

cd /path/to/ObsidianConnector
npm install
cp .env.example .env
mkdir -p config
npm run typecheck && npm test && npm run build

Use Linux paths in the configuration when launching the server from WSL/Linux. A Windows client should launch the Windows Node executable and use Windows vault paths.

Secure vault model

The model can access only vaults in the registry. Use list_vaults first, then pass the returned vault name to other tools. Note paths must be relative Markdown paths. Absolute paths, .. traversal, null bytes, symlink escapes, .obsidian, .trash, node_modules, hidden directories, and non-Markdown note paths are rejected. Read-only vaults reject all mutations.

Automated tests create temporary vaults and never modify your actual Obsidian vault.

Codex CLI

Build the server, then register the generated JavaScript entry point:

codex mcp add obsidian-local -- node ABSOLUTE_PATH_TO_PROJECT/dist/index.js

If the path contains spaces, quote the executable argument as required by your shell or Codex CLI version.

Codex IDE

Use the IDE's MCP server configuration and select a local STDIO server. Set the command to node, set the argument to the absolute path ending in dist/index.js, and set OBSIDIAN_MCP_CONFIG in the server environment if the registry is not at config/vaults.json. Restart the IDE after changing the server configuration.

ChatGPT Desktop

Add a local MCP/connector entry using the STDIO command and absolute dist/index.js path. The command is node; the argument is the server path. Add OBSIDIAN_MCP_CONFIG as an environment variable when using a custom registry. Do not configure an HTTP URL: this server intentionally has no HTTP transport.

Tool reference and example prompts

Start with: “List my registered Obsidian vaults.” Then choose a returned vault name.

  • list_vaults: “List every registered vault and show which are read-only.”

  • get_vault: “Show the configuration for the personal vault.”

  • create_vault: “Create and register a writable vault named scratch under the configured G:\\My Drive\\.obsidian parent directory.”

  • register_vault: “Register this existing vault as work in read-only mode.”

  • unregister_vault: “Unregister the scratch vault without deleting its files.”

  • list_directory: “List the Markdown notes and safe child directories in personal/Projects.”

  • create_directory: “Create the Projects/2026 directory in the writable personal vault.”

  • list_notes: “List all notes under personal/Projects.”

  • search_notes: “Search personal for quarterly review, returning at most 10 excerpts.”

  • read_note: “Read personal/Projects/plan.md.”

  • create_note: “Create personal/Projects/plan.md with this content; do not overwrite it if it exists.”

  • update_note: “Update that note only if its content hash is this expected SHA-256 value.”

  • append_note: “Append this timestamped section to personal/Projects/plan.md.”

  • move_note: “Move personal/Projects/draft.md to personal/Projects/archive/draft.md and reject collisions.”

  • delete_note: “Move personal/Projects/old.md to the vault trash.”

  • get_frontmatter: “Show the YAML frontmatter for personal/Projects/plan.md.”

  • update_frontmatter: “Merge status: done and updated: 2026-07-30 into that note's frontmatter.”

  • list_tags: “List tags used under personal/Projects.”

  • list_backlinks: “List notes linking to personal/Projects/plan.md with Obsidian wiki links.”

  • append_daily_note: “Append this entry to today's configured daily note in personal.”

  • get_project_context: “Read the canonical project notes from personal with bounded content and report missing notes.”

  • get_project_activity: “Extract current tasks, decisions, risks, changelog entries, and recent daily notes from personal.”

Write safety

create_note refuses existing notes unless overwrite: true. update_note accepts an expected content hash to detect concurrent changes. Writes use a temporary file and rename. delete_note moves the note into <vault>/.trash with a collision-safe name. Daily notes are created when absent and appended without replacing existing content.

Development

npm run dev          # run TypeScript directly over STDIO
npm run start        # run dist/index.js
npm run build        # compile to dist/
npm test             # unit and integration tests using temporary vaults
npm run typecheck    # TypeScript compiler check
npm run lint         # ESLint
npm run format       # Prettier write
npm run format:check # Prettier verification

Diagnostics go to stderr. Stdout is reserved for MCP protocol messages.

Verification and MCP Inspector

Run:

npm run format:check
npm run lint
npm run typecheck
npm test
npm run build
npx @modelcontextprotocol/inspector node ABSOLUTE_PATH_TO_PROJECT/dist/index.js

Use temporary test-vault configuration when inspecting write tools. Confirm the tool list, schemas, valid calls, validation errors, traversal rejection, symlink rejection, and stdout/stderr behavior.

Troubleshooting

  • No registered vaults: create config/vaults.json, set OBSIDIAN_MCP_CONFIG, or call register_vault with an existing directory.

  • New vault location: create_vault always creates <vault name> under G:\\My Drive\\.obsidian; it does not accept an arbitrary path.

  • Vault directory does not exist: check spelling and Windows escaping in JSON; register_vault does not create missing roots.

  • Access rejected: use a registered vault name and a vault-relative .md path; do not use absolute paths or ...

  • Read-only error: register the vault with readOnly: false only when mutations are intended.

  • Hash mismatch: re-read the note and use the returned current contentHash before updating.

  • MCP connection failure: run npm run build, use the absolute dist/index.js path, and ensure Node.js 20+ is available to the client.

  • Protocol or JSON errors: do not add console.log statements; diagnostics must use stderr.

  • Inspector cannot start: run the inspector against the built entry point and a temporary registry; do not point tests at the real vault.

Available Tools

22 tools
append_daily_noteA

Create or append to the configured daily note without overwriting existing content.

Inputs: vault (required), content (required), date.

append_noteA

Append content to an existing Markdown note without replacing it.

Inputs: path (required), vault (required), content (required).

create_directoryB

Create a directory inside a registered writable vault.

Inputs: vault (required), directory (required).

create_noteA

Create a Markdown note; it fails if the note exists unless overwrite is explicitly true.

Inputs: path (required), vault (required), content (required), overwrite.

create_vaultB

Create and register a new vault under the configured Obsidian vault parent directory.

Inputs: name (required), readOnly, dateFormat, dailyDirectory.

delete_noteA
Destructive

Move a Markdown note to the vault trash instead of permanently deleting it.

Inputs: path (required), vault (required).

get_frontmatterB
Read-only

Read YAML frontmatter properties from a Markdown note.

Inputs: path (required), vault (required).

get_project_activityB
Read-only

Extract current project tasks, decisions, risks, changelog entries, and recent daily notes.

Inputs: vault (required), maxChars, dailyLimit.

get_project_contextA
Read-only

Read the canonical project notes from a registered vault with bounded content and missing-note reporting.

Inputs: vault (required), maxChars.

get_vaultA
Read-only

Get metadata for one registered vault by name.

Inputs: vault (required).

list_directoryA
Read-only

List Markdown files and safe child directories inside a registered vault directory.

Inputs: vault (required), directory.

list_notesA
Read-only

List Markdown notes in a registered vault, optionally below a directory.

Inputs: vault (required), directory.

list_tagsA
Read-only

List tags found in note frontmatter and Markdown hashtag syntax.

Inputs: vault (required), directory.

list_vaultsA
Read-only

List the explicitly registered Obsidian vaults available for selection.

Inputs: no named parameters.

move_noteA

Move a Markdown note inside a registered vault, rejecting an existing destination by default.

Inputs: vault (required), sourcePath (required), destinationPath (required), overwrite.

read_noteA
Read-only

Read one Markdown note from a registered vault.

Inputs: path (required), vault (required).

register_vaultB

Register an existing Obsidian vault path for safe access.

Inputs: name (required), path (required), readOnly, dateFormat, +1 more.

search_notesA
Read-only

Search registered-vault filenames, Markdown content, tags, and YAML frontmatter with bounded excerpts.

Inputs: query (required), vault (required), limit, directory.

unregister_vaultA

Remove a vault from the local registry without deleting its files.

Inputs: vault (required).

update_frontmatterA

Merge selected YAML frontmatter properties without replacing the note body.

Inputs: path (required), vault (required), properties (required).

update_noteA

Replace a Markdown note, optionally requiring an expected SHA-256 hash for concurrency safety.

Inputs: path (required), vault (required), content (required), expectedHash.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.6/5.0

    Scored across 22 tools

    Disambiguation4/5

    Most tools have clear resource-action boundaries (e.g., read_note vs get_frontmatter vs search_notes). A few pairs like list_notes/list_directory and get_project_context/get_project_activity could cause initial confusion but descriptions resolve them.

    Naming Consistency5/5

    All tools follow a consistent verb_noun snake_case pattern, with verbs like get, list, create, update, delete, search, move, append. No mixed conventions.

    Tool Count3/5

    22 tools fall into the heavy range (16-25). While each tool has a specific function, the overall surface is broad and might be more than needed for typical Obsidian workflows.

    Completeness4/5

    Note lifecycle is fully covered (create/read/update/append/delete/search), plus vault registration and frontmatter handling. Missing directory deletion/rename and note metadata operations, but these are minor gaps.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables comprehensive access to Obsidian vaults through MCP, supporting multi-vault management, knowledge graph analysis, canvas manipulation, dataview queries, template rendering, and periodic notes creation. Provides both local filesystem and remote API connectivity for complete Obsidian integration.
      29
      7,721 npm
      22
      Apache 2.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP clients to interact with Obsidian vaults via filesystem operations and optional REST API integration for advanced UI commands. It features multi-vault auto-discovery, concurrent-safe file handling, and comprehensive tools for searching, reading, and managing vault content.
      12
      7,721 npm
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables MCP-compatible AI hosts to read, search, link, and write notes in a local Obsidian vault with sandboxed file access.
      1
      1
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents and development tools to interact with Obsidian vaults via MCP, providing direct filesystem access for reading, writing, searching, and managing notes without requiring Obsidian to be running.
      Apache 2.0