{
  "markdown": "# obsidian-mcp-secure\n\n[![npm version](https://img.shields.io/npm/v/obsidian-mcp-secure?color=CB3837&logo=npm)](https://www.npmjs.com/package/obsidian-mcp-secure)\n[![npm downloads](https://img.shields.io/npm/dm/obsidian-mcp-secure)](https://www.npmjs.com/package/obsidian-mcp-secure)\n[![MCP Registry](https://img.shields.io/badge/MCP_Registry-listed-5A67D8)](https://registry.modelcontextprotocol.io)\n[![license](https://img.shields.io/npm/l/obsidian-mcp-secure)](LICENSE)\n[![npm audit](https://img.shields.io/badge/npm%20audit-0%20vulnerabilities-brightgreen)](package.json)\n[![CI](https://github.com/dewtech-technologies/obsidian-mcp-secure/actions/workflows/ci.yml/badge.svg)](https://github.com/dewtech-technologies/obsidian-mcp-secure/actions/workflows/ci.yml)\n[![coverage](https://img.shields.io/badge/coverage-unit%20tested-brightgreen)](test/)\n[![Smithery](https://smithery.ai/badge/wleandro-oliveira/obsidian-mcp-secure)](https://smithery.ai/servers/wleandro-oliveira/obsidian-mcp-secure)\n\n> Secure Model Context Protocol server that turns your Obsidian vault into a reliable data source for any MCP-compatible AI client — built from scratch with OWASP Top 10 controls and full audit logging.\n\nListed on the [official Anthropic MCP Registry](https://registry.modelcontextprotocol.io) as `io.github.dewtech-technologies/obsidian-mcp-secure`.\n\n---\n\n## 🧭 Positioning — this is NOT a plugin for Obsidian\n\nIt's the opposite: it's a **bridge that lets Claude Desktop (or any MCP client) read and write inside Obsidian safely**. Your AI assistant stays where it lives; your vault becomes a structured, auditable datasource it can reach.\n\n```\n┌─────────────────┐   MCP    ┌──────────────────────┐   HTTP   ┌────────────────────┐   FS   ┌─────────────┐\n│                 │  stdio   │                      │  :27123  │                    │        │             │\n│ Claude Desktop  │ ───────▶ │ obsidian-mcp-secure  │ ───────▶ │  Local REST API    │ ─────▶ │  Vault .md  │\n│  (AI client)    │          │  (this package)      │          │ (Obsidian plugin)  │        │             │\n└─────────────────┘          └──────────────────────┘          └────────────────────┘        └─────────────┘\n```\n\n| Role in the pipeline | Component |\n|---|---|\n| Where you talk | **Claude Desktop** (or any MCP client) |\n| Bridge / access control | **`obsidian-mcp-secure`** (this package) |\n| Data gateway inside Obsidian | **Local REST API plugin** (by Adam Coddington) |\n| Your knowledge | `.md` files in your vault |\n\n**One-liner:** *Claude is the brain, this MCP is the arm, Obsidian is the memory.*\n\n### Why another Obsidian + AI integration?\n\nThere are plugins that put Claude *inside* Obsidian. This is the inverse, and it exists because:\n\n- **Your assistant is Claude Desktop** — that's where the general-purpose conversations happen. Your notes become one of many contexts Claude can reach, alongside web, GitHub, filesystems, etc.\n- **Security is a first-class concern** — deliberate attack surface, no shell access, path traversal blocked, inputs validated with Zod, every call audited.\n- **Zero build, zero account** — `npx obsidian-mcp-secure` and done. Works on Windows, macOS, Linux the same way.\n- **Composability** — combine this MCP with fetch, filesystem, git, GitHub, etc., and Claude can cross-reference your vault with external sources in a single conversation.\n\n---\n\n## 🛠️ Available Tools\n\n| Tool | Purpose |\n|------|---------|\n| `read_note` | Read a note by path |\n| `list_notes` | List files/folders in the vault or a subdirectory |\n| `create_note` | Create a new `.md` note |\n| `edit_note` | Overwrite an existing note (previous content goes to the audit log) |\n| `delete_note` | Delete a note — **requires `confirm: true`** (Zod rejects otherwise) |\n| `search_notes` | Full-text / tag search using Obsidian's own search engine |\n| `find_note_by_name` | Find notes by partial name — case-insensitive, no exact path needed |\n| `list_tags` | Enumerate all tags in the vault with usage count; sortable by name or frequency |\n| `create_backlinks` | Add `[[wikilinks]]` to a `## Relacionadas` section in a note — explicit and auditable |\n\n---\n\n## 🔒 Security — OWASP Top 10\n\n| Control | Implementation |\n|---------|----------------|\n| **A01** — Broken Access Control | Path traversal blocked (`../`, `..\\\\`, encoded variants); `.md` extension enforced |\n| **A02** — Cryptographic Failures | API key read from `.env` or process env; never hardcoded, never logged |\n| **A03** — Injection | All inputs validated with Zod schemas; no `eval`, no `exec`, no shell |\n| **A04** — Insecure Design | 512 KB max note size; 50-result cap on search; destructive ops require explicit `confirm: true` |\n| **A05** — Security Misconfiguration | Only `127.0.0.1` / `localhost` accepted as host |\n| **A09** — Logging & Monitoring | Full audit log via winston with size-based rotation (5 MB / 10 files) |\n\nEvery tool call emits an audit line with `action`, `params` (sanitized), `success`, `error`, and `timestamp`.\n\n---\n\n## ⚡ Installation\n\n### Prerequisites\n\n1. [**Obsidian Desktop**](https://obsidian.md) with a vault open\n2. The [**Local REST API plugin**](https://github.com/coddingtonbear/obsidian-local-rest-api) (by Adam Coddington) — install from Community Plugins, enable it, and:\n   - Turn on **\"Enable Non-encrypted (HTTP) Server\"** (simpler than HTTPS self-signed certs)\n   - Copy the **API Key** shown in the plugin settings\n3. **Node.js 18+**\n4. **Claude Desktop** (or another MCP-compatible client)\n\n### Configure Claude Desktop\n\nOpen `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows (or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS) and add:\n\n```json\n{\n  \"mcpServers\": {\n    \"obsidian-secure\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"obsidian-mcp-secure\"],\n      \"env\": {\n        \"OBSIDIAN_API_KEY\": \"your-api-key-from-the-plugin\",\n        \"OBSIDIAN_HOST\": \"http://127.0.0.1\",\n        \"OBSIDIAN_PORT\": \"27123\",\n        \"LOG_DIR\": \"C:/path/to/your/logs\"\n      }\n    }\n  }\n}\n```\n\n> **Windows tip:** if `npx` fails silently, switch `\"command\": \"npx\"` to `\"command\": \"npx.cmd\"`. Some Claude Desktop builds don't resolve bare `npx` on PATH.\n\nRestart Claude Desktop (tray → **Quit**, then reopen) and the 9 tools will show up under `obsidian-secure`.\n\n---\n\n## 🤝 Recommended companions\n\nThe real power of MCPs is composability. To reproduce the *\"read my note → fetch a URL → tell me if I'm applying it correctly\"* workflow, add the official **fetch** MCP alongside this one:\n\n```json\n{\n  \"mcpServers\": {\n    \"obsidian-secure\": { \"...\": \"as above\" },\n    \"fetch\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@modelcontextprotocol/server-fetch\"]\n    }\n  }\n}\n```\n\nNow Claude has both your vault and the live web in a single conversation.\n\n---\n\n## 💬 Example prompts\n\nWith `obsidian-secure` + `fetch` enabled:\n\n> *\"Read my note `Projeto API Atendimento.md`, then fetch https://developers.facebook.com/docs/whatsapp and tell me if my implementation matches the latest best practices.\"*\n\n> *\"Search my vault for the tag `#ideia` and summarize the three ideas that appear most often. Then create a new note called `Ideias recorrentes.md` with the summary.\"*\n\n> *\"Read `Atomic Habits - Resumo.md`, fetch https://jamesclear.com/atomic-habits, and point out where my notes drifted from the original.\"*\n\nClaude will orchestrate the tool calls automatically — no manual chaining.\n\n---\n\n## 🧩 Comparison with in-Obsidian plugins\n\nIf your workflow lives inside Obsidian's sidebar, plugins like [`obsidian-claude-code`](https://github.com/Roasbeef/obsidian-claude-code) are the right fit. This MCP targets a different shape:\n\n| Dimension | `obsidian-claude-code` (in-Obsidian) | `obsidian-mcp-secure` (this) |\n|---|---|---|\n| Where the AI lives | Sidebar inside Obsidian | Claude Desktop (or any MCP client) |\n| Setup | `git clone` + `bun build` | `npx obsidian-mcp-secure` |\n| Tools | Read/Write/Edit + Bash + Grep + Glob + WebFetch | 9 purpose-built, Zod-validated tools |\n| Security posture | Full shell access to dev machine | Tight allowlist, audited, OWASP Top 10 |\n| Distribution | Manual clone, requires Bun | npm + official MCP Registry |\n| Composability with other sources | Inside its own sandbox | Any MCP-compatible client can mix it with fetch, GitHub, filesystem, etc. |\n| Best for | Dev who lives in Obsidian | Professional whose main surface is Claude Desktop |\n\nBoth are valid — they occupy different niches.\n\n---\n\n## 🔧 Environment variables\n\n| Variable | Required | Default | Description |\n|----------|:--------:|---------|-------------|\n| `OBSIDIAN_API_KEY` | ✅ | — | API key from the Local REST API plugin |\n| `OBSIDIAN_HOST` | | `http://127.0.0.1` | Host (only `127.0.0.1` and `localhost` are accepted) |\n| `OBSIDIAN_PORT` | | `27123` | Port of the plugin's HTTP server |\n| `LOG_DIR` | | `./logs` | Directory for the audit log files |\n\n---\n\n## 🗺️ Roadmap\n\n### ✅ Shipped in v1.2.1\n\n- [x] Bug fix: `find_note_by_name` searches full path (folder + filename)\n- [x] Bug fix: `list_tags` normalizes all API response formats (object, array of strings, array of objects with `tagCount`/`taggedFilesCount`)\n\n### ✅ Shipped in v1.2.0\n\n- [x] DXT package for one-click install in Claude Desktop (`npm run build:dxt`)\n\n### ✅ Shipped in v1.1.0\n\n- [x] `find_note_by_name` — partial, case-insensitive name match across the entire vault\n- [x] `create_backlinks` — connect related notes with `[[wikilinks]]` (explicit, auditable)\n- [x] `list_tags` — enumerate all tags in the vault with usage count\n- [x] Unit test suite (70 tests — utils, handlers, HTTP client) with Vitest\n- [x] CI pipeline on every PR: tests + coverage + `npm audit` + static security analysis\n\n### 🔜 Up next\n\n- [ ] Smithery listing\n- [ ] Read-only mode flag for shared / multi-user setups\n\nIdeas and PRs welcome — see [CONTRIBUTING.md](CONTRIBUTING.md).\n\n---\n\n## 📜 License\n\nMIT — see [LICENSE](LICENSE).\n\n## 🙏 Credits\n\n- [Model Context Protocol](https://modelcontextprotocol.io) by Anthropic\n- [Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) by Adam Coddington — the foundation that makes this possible\n- Built at [Dewtech](https://github.com/dewtech-technologies) by [Wanderson Leandro](https://github.com/wleandrooliveira)\n\n---\n\n**Security issues?** See [SECURITY.md](SECURITY.md) for disclosure instructions.\n",
  "bytes": 10356,
  "sha": "ef13b3f77bc40e13aaad3e1ac59c2c0efc36159b00c1d46392558a6551ee3fde",
  "repo_slug": "dewtech-technologies/obsidian-mcp-secure",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_dewtech_technologies_obsidian__e0f4863e/readme"
}