能力标签

🔌 MCP 🤖 Agent 🔄 工作流 🌐 翻译 🐳 Docker 💻 CLI 🔗 REST API 🧬 Embedding 🧠 Claude ✨ GPT

🔌

MCP工具

Obsidian MCP

基于 TypeScript · 让 AI 助手直接操作你的系统与工具

英文名：obsidian-mcp-pro

⭐ 19 Stars 🍴 4 Forks 💻 TypeScript 📄 MIT 🏷 AI 8.0分

8.0AI 综合评分

mcpobsidiantypescript

⬇ 下载源码 ZIP ⚙️ 配置说明

✦ AI Skill Hub 推荐

Obsidian MCP 是 AI Skill Hub 本期精选MCP工具之一。综合评分 8.0 分，整体质量较高。我们强烈推荐将其纳入你的 AI 工具库，帮助提升工作效率。

📚 深度解析

Obsidian MCP 是一款基于 MCP（Model Context Protocol）标准协议的 AI 工具扩展。MCP 协议由 Anthropic 开发并开源，旨在建立 AI 模型与外部工具之间的标准化通信接口，目前已被 Claude Desktop、Claude Code、Cursor 等主流 AI 工具采纳。

通过安装 Obsidian MCP，你的 AI 助手将获得额外的工具调用能力，可以用自然语言直接操控该工具的功能，无需学习复杂的命令行语法。MCP 工具的核心价值在于"一次配置，永久增强"——配置完成后，每次与 AI 对话时都可以无缝调用这些工具。

在技术实现上，MCP 工具通过标准的 JSON-RPC 协议与 AI 客户端通信，工具的功能以"工具列表"的形式暴露给 AI 模型，AI 可以按需调用。Obsidian MCP 提供了结构化的工具调用接口，使 AI 模型能够精确地理解和使用每个功能点，显著降低 AI 在工具使用上的错误率。

与传统的 API 集成相比，MCP 工具的优势在于无需编写代码——用户只需在配置文件中添加几行 JSON，即可让 AI 获得全新能力。AI Skill Hub 将 Obsidian MCP 评为 AI 评分 8.0 分，属于同类工具中的优质选择。

📋 工具概览

Obsidian MCP 是一款遵循 MCP（Model Context Protocol）标准协议的 AI 工具扩展。通过 MCP 协议，它可以让 Claude、Cursor 等主流 AI 客户端直接访问和操作外部工具、数据源和服务，实现 AI 能力的无缝扩展。无论是文件操作、数据库查询还是 API 调用，都可以通过自然语言在 AI 对话中直接触发，极大提升生产效率。

GitHub Stars

⭐ 19

开发语言

TypeScript

支持平台

Windows / macOS / Linux

维护状态

轻量级项目，按需更新

开源协议

MIT

AI 综合评分

8.0 分

工具类型

MCP工具

Forks

📖 中文文档

以下内容由 AI Skill Hub 根据项目信息自动整理，如需查看完整原始文档请访问底部「原始来源」。

📌 核心特色

通过标准 MCP 协议与 Claude、Cursor 等主流 AI 客户端深度集成
提供结构化工具调用接口，显著降低 AI 集成复杂度
支持 Claude Desktop 和 Claude Code 无缝接入，开箱即用
可与其他 MCP 工具组合叠加，构建完整 AI 工作站
轻量无侵入设计，不影响现有系统架构

🎯 主要使用场景

在 Claude Desktop 对话中直接调用本地工具，实现 AI 与系统的深度联动
通过自然语言驱动复杂的多步骤自动化任务，代替繁琐手动操作
将多个 MCP 工具组合使用，构建个人专属 AI 工作站

以下安装命令基于项目开发语言和类型自动生成，实际以官方 README 为准。

安装命令

# 方式一：通过 Claude Code CLI 一键安装
claude skill install https://github.com/rps321321/obsidian-mcp-pro

# 方式二：手动配置 claude_desktop_config.json
{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-pro"]
    }
  }
}

# 配置文件位置
# macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
# Windows: %APPDATA%/Claude/claude_desktop_config.json

📋 安装步骤说明

确认已安装 Node.js（v18 或以上版本）
打开 Claude Desktop 或 Claude Code 的 MCP 配置文件
按「交给 Agent 安装 → Claude Desktop」标签中的 JSON 配置填入 mcpServers 字段
保存配置文件并重启 Claude 客户端
重启后，在对话中即可使用本工具

以下用法示例由 AI Skill Hub 整理，涵盖最常见的使用场景。

常用命令 / 代码示例

# 安装后在 Claude 对话中直接使用
# 示例：
用户: 请帮我用 Obsidian MCP 执行以下任务...
Claude: [自动调用 Obsidian MCP MCP 工具处理请求]

# 查看可用工具列表
# 在 Claude 中输入："列出所有可用的 MCP 工具"

以下配置示例基于典型使用场景生成，具体参数请参照官方文档调整。

配置示例

// claude_desktop_config.json 配置示例
{
  "mcpServers": {
    "obsidian_mcp": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-pro"],
      "env": {
        // "API_KEY": "your-api-key-here"
      }
    }
  }
}

// 保存后重启 Claude Desktop 生效

📑 README 深度解析真实文档完整度 82/100 查看 GitHub 原文 →

以下内容由系统直接从 GitHub README 解析整理，保留代码块、表格与列表结构。

简介

Features

Operational features

Folder-scoped permissions: OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS allowlists gate every tool at the path-resolution choke point
Persistent mtime cache at <vault>/.obsidian/cache/mcp-pro-index-cache.json survives restarts; subsequent vault scans serve from cache after one stat-pass
Progress notifications (notifications/progress) on rename_tag, find_unused_attachments, and index_vault when the client subscribes via _meta.progressToken
Elicitation prompts the user to retype the note path on delete_note(permanent: true) when the client supports it

---

What's New

v1.8.2 rolls in a deeper-dive audit pass on top of 1.8.1:

- rename_tag and other vault-wide bulk writers now hold the same rewrite lock as move_note / delete_note. Closes a cross-tool TOCTOU where running tag-rename concurrently with a move could surface "content changed during move" failures and leave stale links. - applyRewrites retries failed edits via content search. When bytes shift between plan and apply (Obsidian sync, text editor, concurrent tool), the apply step now finds the unique expected substring at its new position and splices there. If ambiguous or missing, the failure is still surfaced rather than corrupting the file. - planMoveRewrites and planDeleteRewrites now read each note exactly once. The previous two-pass implementation doubled I/O on rename / delete operations across large vaults. - CommonMark fenced-code indentation now matches the spec. Lines with more than 3 leading spaces no longer falsely close a fenced block (and don't expose subsequent content to wikilink rewriting). - /health no longer leaks the live session count when a Bearer token is configured. Status + version stay public for monitoring; sessions is dropped in authenticated deployments. Local-only setups still see it. - constantTimeEqual is now fully length-safe (pads both inputs to a fixed width before comparing), and the regex / parser hardening list also closed: resolveWikilink proximity tie-break for path-suffix matches, escaped ] in markdown link labels, control- character validation on runInstall.vaultName, backup-path hint on install write failure, and mapConcurrent return-value usage in the canvas planner. - npm audit clean. Resolved 4 moderate-severity advisories in transitive devDependencies. Production deps were already clean.

v1.8.1 was a security and correctness patch on top of 1.8.0:

- CRITICAL: permission allowlist bypass via .. segments closed. v1.8.0 evaluated OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS against the raw user-supplied path before path.resolve collapsed ... An input like Allowed/../OtherFolder/note.md slipped past the prefix check. assertAllowed now collapses .. via path.posix.normalize and rejects any path that climbs above its starting point. Six regression tests cover the bypass classes. - HIGH: HTTP timeout on every embedding-provider fetch (AbortSignal.timeout(30s)), TOCTOU race in rename_tag closed by moving the rewrite inside updateNote's transform, and search_semantic / find_similar_notes now invalidate stale vectors when the active provider/model differs from what produced the index. - MEDIUM: depth guard on Bases filter recursion, updateNote skips the disk write when the transform returns unchanged content (no more spurious mtime bumps on no-op tools), and embedding-provider error bodies are truncated to 200 chars before being interpolated into thrown errors. - LOW: empty accept elicitation responses are now cancellations, not errors, and the in-memory mtime cache snapshot orders by content length so small entries fill the budget first.

v1.8.0 was the largest feature drop since v1.0:

Surgical edits by heading and block id. update_section, insert_at_section, list_sections, replace_in_note, edit_block, plus fragment retrieval modes on get_note (section, block, lines).
Bases support. list_bases, read_base, query_base for Obsidian's database-view files. First filesystem-only MCP server to ship native Bases.
Semantic search. index_vault, search_semantic, find_similar_notes backed by Ollama (default) or OpenAI. Persistent vector index with content-hash incremental updates.
Attachments. list_attachments, find_unused_attachments, get_attachment (returns image / audio / blob bytes inline).
Tag renames vault-wide. rename_tag rewrites both inline #tag and frontmatter tags: (hierarchical mode rebases nested sub-tags).
Folder-scoped permissions. OBSIDIAN_READ_PATHS / OBSIDIAN_WRITE_PATHS allowlists.
Persistent mtime cache. Vault-wide scans (get_tags, search_notes, search_by_tag) hydrate from <vault>/.obsidian/cache/mcp-pro-index-cache.json after a restart and stat-pass against current state, only re-reading changed notes.
Quick wins. get_recent_notes, get_vault_stats, resolve_alias.
MCP prompts. daily-review, weekly-rollup, find-stale-notes, extract-action-items, build-moc.
Progress notifications on rename_tag, find_unused_attachments, index_vault.
Elicitation on delete_note(permanent: true) for clients that support it.
eslint wired up with typescript-eslint flat config; npm run lint and lint:fix.

v1.7.0 — delete_note reference handling:

delete_note can strip references vault-wide when permanent: true is paired with removeReferences: true. Wikilinks fall back to alias-or-basename, markdown links fall back to visible text, embeds drop entirely, fragments are discarded. Trash-mode (default) leaves references intact since trashed files stay recoverable.
Concurrent-safe rewrites — move_note (with updateLinks: true) and delete_note (with removeReferences: true) serialize per vault, removing the partial-failure mode for parallel rewrite-bearing operations.

v1.6.0 — Obsidian-parity link maintenance:

move_note rewrites references across the vault by default, matching Obsidian's "Automatically update internal links" behavior. Wikilinks (with aliases / fragments preserved), markdown links, and canvas nodes[].file fields all follow the moved file. Output form is preserved when possible.
TOCTOU correctness — every edit's pre-edit content is verified before splicing, so a parallel write_note between plan and apply is surfaced in failedReferrers rather than corrupting referrers silently.
Control-char injection defense — sanitizeError and the new escapeControlChars strip newlines/control bytes from any caller-controlled string before it reaches LLM context. Closes a prompt-injection vector via attacker-named filenames.

Full version history in CHANGELOG.md.

---

Install dependencies

npm install

One-Command Install (Claude Desktop / Cursor)

npx -y obsidian-mcp-pro install

This merges an entry into your claude_desktop_config.json (or ~/.cursor/mcp.json with --client=cursor), backs up the previous file, and prints next steps. Works on macOS, Windows, and Linux.

Pin a specific vault:

npx -y obsidian-mcp-pro install --vault /path/to/your/vault

Build

npm run build

Quick Start

Using Obsidian? There's also an Obsidian plugin that runs this server inside the app with a ribbon toggle and settings UI — no config-file editing. Recommended for most users.

Usage

Once installed, the server exposes 23 tools and 3 resources to whichever MCP client you configured. Below is a transcript of a Claude Desktop conversation showing what day-to-day use looks like.

You: Find notes tagged #project I touched this week, then summarize the status of each and append today's date under a "Last reviewed" heading in each one.

Claude picks the right tools in order, with no guidance beyond the prompt:

🔧 search_by_tag(tag="project", includeContent=false)
  → 7 notes: "Atlas/overview.md", "Atlas/milestones.md", "Beacon/spec.md", ...

🔧 list_notes(folder="Atlas", limit=100)
  → filters to recent modifications via get_note stats

🔧 get_note(path="Atlas/overview.md")
  → reads content + frontmatter + tags

🔧 get_note(path="Atlas/milestones.md")
  → ...

🔧 append_to_note(
    path="Atlas/overview.md",
    content="\n## Last reviewed\n2026-04-21 — on track; waiting on design review."
  )
  → ok

🔧 append_to_note(
    path="Atlas/milestones.md",
    content="\n## Last reviewed\n2026-04-21 — Q2 milestone at risk, see spec.md."
  )
  → ok

Claude: I reviewed 7 project notes tagged #project. Atlas is on track pending design review; the Q2 milestone is at risk — details in milestones.md. Beacon's spec is complete but has 3 open questions in the frontmatter. I appended a "Last reviewed" section to each.

Other things the tool set lets agents do without hand-holding:

Research a topic across the vault. search_notes → get_outlinks → get_graph_neighbors walks the graph to depth=2 and surfaces related notes the user may have forgotten.
Clean up dangling references after a rename. move_note → find_broken_links returns every wikilink that now points nowhere, with source note and line number.
Maintain a daily log. get_daily_note reads today's note (using the vault's configured date format) and append_to_note adds the new entry — daily-note plugin config is honored, no manual date formatting.
Canvas editing. read_canvas → agent reasons about the node graph → add_canvas_node + add_canvas_edge lays out new ideas on an existing board.

Tool descriptions + typed schemas + safety hints (readOnlyHint, destructiveHint) are what make this work reliably — the agent knows delete_note is destructive and asks first, knows search_notes is free to call speculatively, and knows the expected shape of every argument.

---

Semantic Search (optional, Ollama or OpenAI)

index_vault chunks each note (heading-aware), embeds via the configured provider, persists vectors to <vault>/.obsidian/cache/, and incrementally re-embeds only changed notes
search_semantic ranks notes by cosine similarity against an embedded query
find_similar_notes reuses an existing note's embeddings to surface neighbors without a live API call

Manual Claude Desktop Config

Add this to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-pro"]
    }
  }
}

If you have multiple vaults, specify which one:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-mcp-pro"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Configuration

The server locates your vault using the following priority:

Priority	Method	Description
1	`OBSIDIAN_VAULT_PATH`	Environment variable with the absolute path to your vault
2	`OBSIDIAN_VAULT_NAME`	Environment variable to select a vault by folder name when multiple vaults exist
3	Auto-detection	Reads Obsidian's global config (`obsidian.json`) and uses the first valid vault found

Auto-detection works on macOS, Windows, and Linux by reading the platform-specific Obsidian configuration directory.

"No Obsidian vault configured" on Startup

The server couldn't locate a vault. Resolution order is:

OBSIDIAN_VAULT_PATH env var (absolute path) — always wins if set.
OBSIDIAN_VAULT_NAME env var — picks a named vault from Obsidian's global config.
Auto-detection — reads obsidian.json (platform-specific) and uses the first valid vault found.

Fastest fix: set OBSIDIAN_VAULT_PATH in the env block of your MCP client's config. Auto-detection fails when Obsidian has never been launched, obsidian.json is missing/corrupt, or all registered vaults resolve to paths that no longer exist.