ObsidianConnector
Provides tools for interacting with Obsidian vaults, including listing vaults, managing directories, reading and writing Markdown notes, searching notes, and accessing frontmatter and backlinks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ObsidianConnector List my registered Obsidian vaults."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 buildThe 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 buildUse 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.jsIf 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 thepersonalvault.”create_vault: “Create and register a writable vault namedscratchunder the configuredG:\\My Drive\\.obsidianparent directory.”register_vault: “Register this existing vault asworkin read-only mode.”unregister_vault: “Unregister thescratchvault without deleting its files.”list_directory: “List the Markdown notes and safe child directories inpersonal/Projects.”create_directory: “Create theProjects/2026directory in the writablepersonalvault.”list_notes: “List all notes underpersonal/Projects.”search_notes: “Searchpersonalforquarterly review, returning at most 10 excerpts.”read_note: “Readpersonal/Projects/plan.md.”create_note: “Createpersonal/Projects/plan.mdwith 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 topersonal/Projects/plan.md.”move_note: “Movepersonal/Projects/draft.mdtopersonal/Projects/archive/draft.mdand reject collisions.”delete_note: “Movepersonal/Projects/old.mdto the vault trash.”get_frontmatter: “Show the YAML frontmatter forpersonal/Projects/plan.md.”update_frontmatter: “Mergestatus: doneandupdated: 2026-07-30into that note's frontmatter.”list_tags: “List tags used underpersonal/Projects.”list_backlinks: “List notes linking topersonal/Projects/plan.mdwith Obsidian wiki links.”append_daily_note: “Append this entry to today's configured daily note inpersonal.”get_project_context: “Read the canonical project notes frompersonalwith bounded content and report missing notes.”get_project_activity: “Extract current tasks, decisions, risks, changelog entries, and recent daily notes frompersonal.”
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 verificationDiagnostics 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.jsUse 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, setOBSIDIAN_MCP_CONFIG, or callregister_vaultwith an existing directory.New vault location:
create_vaultalways creates<vault name>underG:\\My Drive\\.obsidian; it does not accept an arbitrary path.Vault directory does not exist: check spelling and Windows escaping in JSON;
register_vaultdoes not create missing roots.Access rejected: use a registered vault name and a vault-relative
.mdpath; do not use absolute paths or...Read-only error: register the vault with
readOnly: falseonly when mutations are intended.Hash mismatch: re-read the note and use the returned current
contentHashbefore updating.MCP connection failure: run
npm run build, use the absolutedist/index.jspath, and ensure Node.js 20+ is available to the client.Protocol or JSON errors: do not add
console.logstatements; 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 toolsappend_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_noteADestructive
Move a Markdown note to the vault trash instead of permanently deleting it.
Inputs: path (required), vault (required).
get_frontmatterBRead-only
Read YAML frontmatter properties from a Markdown note.
Inputs: path (required), vault (required).
get_project_activityBRead-only
Extract current project tasks, decisions, risks, changelog entries, and recent daily notes.
Inputs: vault (required), maxChars, dailyLimit.
get_project_contextARead-only
Read the canonical project notes from a registered vault with bounded content and missing-note reporting.
Inputs: vault (required), maxChars.
get_vaultARead-only
Get metadata for one registered vault by name.
Inputs: vault (required).
list_backlinksARead-only
List Markdown notes containing Obsidian wiki links to a target note.
Inputs: path (required), vault (required).
list_directoryARead-only
List Markdown files and safe child directories inside a registered vault directory.
Inputs: vault (required), directory.
list_notesARead-only
List Markdown notes in a registered vault, optionally below a directory.
Inputs: vault (required), directory.
list_tagsARead-only
List tags found in note frontmatter and Markdown hashtag syntax.
Inputs: vault (required), directory.
list_vaultsARead-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_noteARead-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_notesARead-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
Scored across 22 tools
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.
All tools follow a consistent verb_noun snake_case pattern, with verbs like get, list, create, update, delete, search, move, append. No mixed conventions.
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.
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
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Search your AI chat history (ChatGPT, Claude, Codex) from any MCP client. Remote, private, read-only
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.297,721 npm22Apache 2.0
- AlicenseAqualityDmaintenanceEnables 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.127,721 npmMIT
- AlicenseAqualityDmaintenanceEnables MCP-compatible AI hosts to read, search, link, and write notes in a local Obsidian vault with sandboxed file access.11MIT
- AlicenseNot gradedqualityBmaintenanceEnables 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