Obsidian MCP 服务器

obsidian-mcp-server 是一个 MCP 服务器，允许 AI 代理查询、搜索和总结 Obsidian 知识库（Vault）中的 Markdown 文档。

通过连接到 MCP 客户端，它可以让代理在控制 Token 使用量的同时查询知识库内容。

功能特性

• 基于关键字的笔记搜索 (vault, action="search")

• 查看特定笔记 (vault, action="read")

• 查询知识库所有文档列表 (vault, action="list_all")

• 查询知识库状态 (vault, action="stats")

• 为长期上下文创建内存包 (vault, action="collect_context")

• 查看已保存的内存笔记 (vault, action="load_memory")

• 自动生成 frontmatter 建议 (generate_property)

• 实际写入 frontmatter (write_property)

• 基于文档的提示词工作流 (create_document_with_properties)

• 整理图片附件 (organize_attachments)

注意事项

此服务器会将知识库内容暴露给客户端。请在生产环境中谨慎使用。

• 请勿连接不可信的 AI 代理。

• 请将知识库路径 (VAULT_DIR_PATH) 限制为最小权限。

• 对于大型知识库，请通过调整 maxOutputChars 和 limit 来控制 Token 成本。

• vault 操作的默认压缩模式为 balanced。

配置检查项

1. 知识库路径：VAULT_DIR_PATH 必须输入绝对路径。

// ✅ 올바른 예시
"VAULT_DIR_PATH": "/Users/username/Documents/MyVault"
"VAULT_DIR_PATH": "C:\\Users\\username\\Documents\\MyVault"  // Windows
"VAULT_DIR_PATH": "/mnt/c/Users/username/Documents/MyVault"  // WSL

// ❌ 잘못된 예시
"VAULT_DIR_PATH": "~/Documents/MyVault"  // 상대 경로 사용 불가
"VAULT_DIR_PATH": "./vault"              // 상대 경로 사용 불가

2. Node.js 要求：必须安装 Node.js 22 或更高版本。

node --version  # v22.0.0 이상 확인

入门指南（快速设置）

1) 通用要求

• 最低配置为 VAULT_DIR_PATH（知识库绝对路径）。

• MCP 的运行方式以发布包为准进行说明。

  • 使用发布包 (npx)（推荐）

  • 本地 build/index.js 仅用于开发/调试目的

• 本地运行将在最后一节 (5) 中单独说明。

• 如果没有知识库路径，启动将失败。

• 以下示例已整理好，可直接复制粘贴使用。

2) 发布包 (npx) 设置

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": {
        "VAULT_DIR_PATH": "/abs/path/to/your/vault",
        "LOGGING_LEVEL": "info"
      }
    }
  }
}

直接运行 CLI：

npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault --logging-level info

3) MCP 客户端配置

尽管不同客户端的 UI 不同，但 command/args/env 的基本形式是一致的。

发布包核心：command="npx", args=["-y","@sunub/obsidian-mcp-server@latest"], env.VAULT_DIR_PATH

[mcp_servers.obsidian]
command = "npx"
args = ["-y", "@sunub/obsidian-mcp-server@latest"]
env = { VAULT_DIR_PATH = "/abs/path/to/your/vault" }

1. 运行 copilot

2. 执行 /mcp add

3. 输入以下值

• Server name: obsidian

• Server Type: [1] Local

• Command: npx -y @sunub/obsidian-mcp-server@latest

• Environment: { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }

由于不同版本的 JSON 键名可能不同（例如 servers/mcpServers），请根据项目文档进行应用。

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
      "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
    }
  }
}

在 Cursor Settings → MCP → New MCP Server 中注册。

{
  "obsidian": {
    "command": "npx",
    "args": ["-y", "@sunub/obsidian-mcp-server@latest"],
    "env": { "VAULT_DIR_PATH": "/abs/path/to/your/vault" }
  }
}

※ 部分版本的服务器标识键名可能不同，请按照设置界面的说明进行粘贴。

包安装型示例：

gemini mcp add obsidian npx -y @sunub/obsidian-mcp-server@latest --vault-path /abs/path/to/your/vault

※ 部分 Gemini 版本对 --vault-path 的支持可能有所不同，请查看 gemini mcp add 的最新文档。

4) 完整配置示例

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "-y",
        "@sunub/obsidian-mcp-server@latest"
      ],
      "env": {
        "VAULT_DIR_PATH": "/path/to/obsidian-vault",
        "VAULT_METRICS_LOG_PATH": "/path/to/vault-metrics.ndjson",
        "LOGGING_LEVEL": "info"
      }
    }
  }
}

环境变量设置

• VAULT_DIR_PATH (必填)：Obsidian 知识库绝对路径

• VAULT_METRICS_LOG_PATH (选填)：将操作响应压缩/Token 指标记录为 JSONL

• LOGGING_LEVEL (选填)：debug | info | warn | error

启动后的快速验证

连接完成后，请先确认以下 3 点。 即使文档无法打开，也能立即缩小故障范围。

1. 检查知识库状态

"Vault 상태를 요약해줘."

预期内部行为：

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": { "action": "stats" }
  }
}

正常运行时，响应中会包含 totalFiles、isInitialized 和 vaultPath。

2. 检查搜索索引

"노트 제목에 'MCP'가 들어간 문서만 5개 찾아줘."

预期内部行为：

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": {
      "action": "search",
      "keyword": "MCP",
      "limit": 5
    }
  }
}

如果 search 结果为空，请检查索引、路径或关键字范围。

3. 检查文档读取

"특정 노트 하나를 읽어줘."

预期内部行为：

{
  "method": "tools/call",
  "params": {
    "name": "vault",
    "arguments": {
      "action": "read",
      "filename": "예: 어떤 문서 이름"
    }
  }
}

如果 filename 错误，会收到 { "error": "Document not found: ..." }，此时先用 list_all 确认候选文件会更快解决问题。

search、list_all 和 load_memory 的 quiet 默认值为 true，因此默认响应可能比较简洁。 如果需要，请同时使用 quiet: false、includeContent: true 和 excerptLength（或 maxOutputChars）来查看详情。

使用示例

比起如何调用 MCP，更重要的是“想要执行什么操作”。

整理 Markdown 文档中引用的附件的操作示例：

https://github.com/user-attachments/assets/eb74ec05-09f7-4632-a22c-666b7e844147

• 当要求整理特定文档中引用的图片附件时，它会在 images 文件夹内创建一个以该文件名为名称的文件夹并进行整理。

• 整理后的文档会更新指向 images 文件夹的链接，以确保原有文档的连接不会断开。

直接运行的问题示例：

• 在 README.md 中只查找 入门指南（快速设置） 的 MCP 客户端配置 部分。

• 阅读并总结 docs/tools-usage-guide.md 中的 vault 配置示例。

• 在 docs/tool-reference.md 中查找 vault 的 collect_context 参数。

• 总结 docs/tools-usage-guide.md 中的 MCP 服务器 配置块。

自然语言示例写得越具体，工具运行就越准确：

• "在 README.md 的入门指南部分中，只查找运行命令示例"

• "在 docs/tools-usage-guide.md 中查找并比较 vault 相关的用法示例"

• "只读取 docs/tool-reference.md 中 vault.read 参数的说明"

vault 会根据用户的问题在内部进行映射并调用，实际流程如下：

• 在 README.md 的入门指南（快速设置）中，只显示 npx 示例 → 提取核心关键字后，首先调用 vault.search。

• 只读取 docs/tool-reference.md 的 collect_context 参数 → 首先通过 vault.read 读取文档的相关部分，必要时通过 vault.collect_context 进行整理。

• 读取 docs/tools-usage-guide.md 中的 frontmatter 处理过程 → 通过 vault.read 找到文档位置后，可以依次调用 generate_property/write_property/create_document_with_properties。

工具调用的具体流程请参考 使用示例（工具调用流程） 中的 JSON 示例。

已注册工具

• Obsidian Tools (6 actions)

  • vault

    • search

    • read

    • list_all

    • stats

    • collect_context

    • load_memory

• generate_property

• write_property

• create_document_with_properties

• organize_attachments

详细使用规范

• 工具详细操作、参数默认值及实际响应格式，请查看 Tool Reference。

• vault 是一个 MCP 工具，实际操作通过 action 值进行分流。拼写错误是导致失败的最常见原因。

• 在大型知识库中，请将 collect_context 的 scope 设置为 "all"，并将 maxDocs 设置得较小，然后逐步扩展。