{"_id":"@phssakaigawa/obsidian-vault-mcp","name":"@phssakaigawa/obsidian-vault-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@phssakaigawa/obsidian-vault-mcp","version":"0.1.0","description":"MCP server for reading and searching an Obsidian vault directly from the filesystem. No Obsidian plugin, no REST API, no running Obsidian required.","license":"MIT","author":{"name":"Shoichiro Sakaigawa"},"type":"module","engines":{"node":">=18"},"bin":{"obsidian-vault-mcp":"dist/index.js"},"repository":{"type":"git","url":"git+https://github.com/phssakaigawa/obsidian-vault-mcp.git"},"homepage":"https://github.com/phssakaigawa/obsidian-vault-mcp#readme","bugs":{"url":"https://github.com/phssakaigawa/obsidian-vault-mcp/issues"},"keywords":["mcp","modelcontextprotocol","obsidian","markdown","notes","claude"],"scripts":{"build":"tsc","watch":"tsc --watch","probe":"node scripts/probe.mjs","prepublishOnly":"npm run build"},"dependencies":{"@modelcontextprotocol/sdk":"^1.30.0","yaml":"^2.8.1","zod":"^4.5.2"},"devDependencies":{"@types/node":"^22.10.0","typescript":"^5.7.0"},"gitHead":"c5bf33781a59916ac1c41814389603e787d24e3c","_id":"@phssakaigawa/obsidian-vault-mcp@0.1.0","_nodeVersion":"24.14.0","_npmVersion":"11.9.0","dist":{"integrity":"sha512-pSMgamKtuozYktJev7JAHlGIj52sWwlyLo9jcgINIhbDNchQfVi3qsi/f3Xb0crm8O4zivcF7AtlqjAzkuqo8w==","shasum":"30abe54ca1c78ffea8a4264d0a156d6c8d0b2c2e","tarball":"https://registry.npmjs.org/@phssakaigawa/obsidian-vault-mcp/-/obsidian-vault-mcp-0.1.0.tgz","fileCount":13,"unpackedSize":59240,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCwkdQyTYpmgpoxOvwI+mkK2imP/2xymvCvg0c5nSK6GgIgVtI9jimPVo6bEVB46PYhFvwxHzj+1S7J0iOvj5lmugY="}]},"_npmUser":{"name":"phssakaigawa","email":"sakaigawa@pumpkinheads.jp"},"directories":{},"maintainers":[{"name":"phssakaigawa","email":"sakaigawa@pumpkinheads.jp"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/obsidian-vault-mcp_0.1.0_1788051960005_0.19477765517215695"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-30T01:05:59.706Z","0.1.0":"2026-08-30T01:06:00.157Z","modified":"2026-08-30T01:06:00.427Z"},"maintainers":[{"name":"phssakaigawa","email":"sakaigawa@pumpkinheads.jp"}],"description":"MCP server for reading and searching an Obsidian vault directly from the filesystem. No Obsidian plugin, no REST API, no running Obsidian required.","homepage":"https://github.com/phssakaigawa/obsidian-vault-mcp#readme","keywords":["mcp","modelcontextprotocol","obsidian","markdown","notes","claude"],"repository":{"type":"git","url":"git+https://github.com/phssakaigawa/obsidian-vault-mcp.git"},"author":{"name":"Shoichiro Sakaigawa"},"bugs":{"url":"https://github.com/phssakaigawa/obsidian-vault-mcp/issues"},"license":"MIT","readme":"# obsidian-vault-mcp\n\nRead-only MCP access to an [Obsidian](https://obsidian.md) vault, straight from the filesystem.\n\nNo Obsidian plugin, no REST API, no running Obsidian. The server reads the `.md` files on\ndisk, so it works when Obsidian is closed, when the vault lives on a synced folder, and on a\nheadless machine.\n\n## Why this one\n\nMost Obsidian MCP servers talk to Obsidian itself through the Local REST API community\nplugin. That is the right design if you want to drive the app — open a note, run a template —\nbut it means the app has to be running, and it puts a plugin in the path of every read.\n\nThis server does the opposite: it treats the vault as what it is on disk, a folder of Markdown\nfiles, and only reads. That makes it dependable in the cases where the REST-API servers are\nnot available at all, at the cost of not being able to drive Obsidian's UI.\n\nIt also searches what the notes *say*, not just what they are called — `search_content` and\n`search_meta` are the tools that make a vault actually useful to an agent.\n\n## Install\n\n```sh\nnpm install -g @phssakaigawa/obsidian-vault-mcp\n```\n\nOr run it without installing:\n\n```sh\nnpx -y @phssakaigawa/obsidian-vault-mcp /path/to/vault\n```\n\nNode 18 or newer.\n\n## Configure\n\nThe server speaks MCP over stdio, so any MCP client can use it. One or more vault directories\nare passed as positional arguments.\n\n**Claude Code**\n\n```sh\nclaude mcp add obsidian -s user -- npx -y @phssakaigawa/obsidian-vault-mcp /path/to/vault\n```\n\n**Claude Desktop** — in `claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"obsidian\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@phssakaigawa/obsidian-vault-mcp\", \"/path/to/vault\"]\n    }\n  }\n}\n```\n\nOn Windows, prefer an absolute path to `node.exe` plus the installed entry point over `npx`;\nit does not depend on `PATH` and does not lose quoting:\n\n```json\n{\n  \"command\": \"C:\\\\Program Files\\\\nodejs\\\\node.exe\",\n  \"args\": [\n    \"C:\\\\path\\\\to\\\\node_modules\\\\@phssakaigawa\\\\obsidian-vault-mcp\\\\dist\\\\index.js\",\n    \"C:\\\\Users\\\\you\\\\Documents\\\\MyVault\"\n  ]\n}\n```\n\n**Any other MCP client** — same `command` / `args`, in whatever config file it uses.\n\n## Tools\n\nAll five are read-only and are annotated as such, so clients that offer per-tool\nauto-approval can safely allow the lot.\n\n| Tool | What it does |\n| --- | --- |\n| `read_notes` | Read the full text of one or more notes. Accepts a vault-relative path, with or without `.md`, or a bare note title. A note that cannot be read is reported in place and does not abort the others. |\n| `search_notes` | Find notes by title or path. Substring by default, regular expression on request. |\n| `search_content` | Full-text search across note bodies. Returns matching lines with line numbers and surrounding context. |\n| `search_meta` | Find notes by YAML frontmatter key/value, or by tag. Tags are read from both the frontmatter `tags` key and inline `#tags` in the body. |\n| `list_notes` | List notes, newest first, optionally under one folder. Paged. |\n\nEvery search takes a `limit`, and the result says when the limit was the reason it stopped.\n\n## Safety\n\nThe vault directories given on the command line are the only thing the server will read.\n\nEach requested path is resolved and checked twice: once as written, and again after symlink\nresolution, so a link inside the vault cannot be used to read a file outside it. Containment\nis separator-aware — a root of `/vault` does not admit `/vault-private`. Relative paths\nresolve against the vault root, not the process working directory, which for an MCP server is\njust wherever the client happened to launch it.\n\nThere is no write path. Nothing in this server opens a file for writing.\n\n`.obsidian`, `.trash`, `.git` and other dot-directories are skipped, so workspace state and\nplugin configuration never reach the model.\n\n## Design notes\n\n**Every runtime import is a declared dependency.** There are three — the MCP SDK, `zod` and\n`yaml` — and all three are in `dependencies` with an explicit range. Relying on a transitive\npackage being hoisted into place works right up until the day the ecosystem moves and the\npackage resolves to a version whose API has changed; the failure then looks like a\nmalformed tool schema rather than a missing module, which is a genuinely confusing thing to\ndebug. Declaring what you import costs one line and removes the whole class of problem.\n\n**Searches stream.** Traversal is an async generator, so a search that reaches its limit\nstops touching the disk at that point instead of walking the whole vault first.\n\n**Frontmatter goes through a real YAML parser.** Frontmatter is arbitrary YAML; a regex\napproach quietly mis-parses nested maps and multi-line strings. A note whose frontmatter does\nnot parse yields no metadata rather than failing the search it appears in.\n\n## Limitations\n\n- Read-only, by design.\n- Only `.md` files. Canvases, attachments and other vault contents are not indexed.\n- No semantic or embedding search; `search_content` is literal and regex matching.\n- Wiki-links are not resolved into a graph. `[[Note]]` is matched as text like any other.\n- No index is kept between calls. Searches walk the vault each time, which is fine for\n  vaults in the low thousands of notes and is the reason there is nothing to invalidate when\n  the vault changes underneath you.\n\n## Development\n\n```sh\nnpm install\nnpm run build\nnode scripts/probe.mjs /path/to/vault\n```\n\n`scripts/probe.mjs` speaks MCP to the built server and prints what a client would see. It\nchecks the thing every client validates first — that each tool advertises an object\n`inputSchema` — then calls each tool and confirms a path outside the vault is refused.\n\n## License\n\nMIT. See [LICENSE](LICENSE) and [NOTICE](NOTICE); the vault boundary check is derived from the\nMIT-licensed Model Context Protocol reference filesystem server, and NOTICE records exactly\nwhat was taken and what was changed.\n","readmeFilename":"README.md","_rev":"1-ae7fe502b1e21feaa56292ee37c77c7e"}