MCP Fs Obsidian

MCP FS黑曜石

一个轻量级的模型上下文协议（MCP）服务器，用于安全访问黑曜石保险库。此服务器为Claude提供了在黑曜石保险库中读写笔记的能力，同时防止YAML前体损坏。

特性

• ✅ 使用灰质进行安全的前体解析和验证
• ✅ 要排除的路径筛选 .obsidian 目录和其他系统文件
• ✅ 核心MCP方法： read_note, write_note, list_directory, delete_note
• ✅ 安全删除，并要求确认，以防止事故发生
• ✅ 使用Bun运行时支持TypeScript（无需编译）
• ✅ 全面的错误处理和验证

先决条件

• 包子 运行时（v1.0.0或更高版本）
• 黑曜石保险库（本地目录 .md 文件）
• Claude Desktop（用于MCP集成）

安装

面向最终用户（推荐）

无需安装！使用 bunx 直接运行：

bunx mcp-fs-obsidian /path/to/your/obsidian/vault

对于开发者

1. 克隆此存储库
2. 使用Bun安装依赖项：

bun install

用法

运行服务器

最终用户：

bunx mcp-fs-obsidian /path/to/your/obsidian/vault

开发者：

bun server.ts /path/to/your/obsidian/vault

Claude桌面配置

单保险库

添加到您的Claude Desktop配置文件中：

{
  "mcpServers": {
    "obsidian": {
      "command": "bunx",
      "args": ["mcp-fs-obsidian", "/Users/yourname/Documents/MyVault"]
    }
  }
}

多个保险库

您可以通过创建单独的MCP服务器条目来配置多个保管库：

{
  "mcpServers": {
    "obsidian-personal": {
      "command": "bunx",
      "args": ["mcp-fs-obsidian", "/Users/yourname/Documents/PersonalVault"]
    },
    "obsidian-work": {
      "command": "bunx",
      "args": ["mcp-fs-obsidian", "/Users/yourname/Documents/WorkVault"]
    },
    "obsidian-research": {
      "command": "bunx",
      "args": ["mcp-fs-obsidian", "/Users/yourname/Documents/ResearchVault"]
    }
  }
}

配置文件位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

例子

问克劳德你的笔记：

• “我的黑曜石保险库里有什么文件？”
• “阅读我的笔记‘projectides.md’”
• “显示标题中带有‘AI’的所有笔记”

让Claude帮助管理笔记：

• “在frontmatter中创建一个名为'meeting notes.md'的新笔记，其中包含今天的日期”
• “更新我的'research.md'注释中的标签，以包含'machine learning'”
• “列出我的“项目”文件夹中的所有标记文件”
• “删除旧的草稿注释'draft ideas.md'（带确认）”

故障排除

常见问题

“找不到命令：bunx”

• 解决方案： 从安装Bun运行时 bun.sh
• 备选方案： 使用npm： npx mcp-fs-obsidian /path/to/vault

“用法：bun-server.ts/path/to/vault”

• 原因： 未提供保险库路径
• 解决方案： 指定黑曜石保管库目录的完整路径

“权限被拒绝”错误

• 原因： 文件系统权限不足
• 解决方案： 确保vault目录对用户可读/可写

“不允许路径遍历”

• 原因： 尝试访问保管库外的文件
• 解决方案： 所有文件路径都必须相对于vault根目录

Claude Desktop无法识别服务器

1. 检查配置文件路径是否适合您的操作系统
2. 确保JSON语法有效（使用JSON验证器）
3. 配置更改后重新启动Claude Desktop
4. 检查Claude Desktop日志中的错误消息

“黑曜石文件仍在显示”

• 预期： 路径过滤器自动排除 .obsidian/** 模式
• 如果仍然看到他们： 过滤器按照安全设计工作

调试模式

运行时记录错误：

bunx mcp-fs-obsidian /path/to/vault 2>debug.log

获取帮助

• 打开一个问题 在GitHub上
• 包括您的操作系统、Bun版本和错误消息
• 提供vault目录结构（不含敏感内容）

测试

运行测试套件：

bun test

API方法

read_note

用解析后的前体阅读保险库中的笔记。

请求：

{
  "name": "read_note",
  "arguments": {
    "path": "project-ideas.md"
  }
}

答复：

{
  "path": "project-ideas.md",
  "frontmatter": {
    "title": "Project Ideas",
    "tags": ["projects", "brainstorming"],
    "created": "2023-01-15T10:30:00.000Z"
  },
  "content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}

write_note

在保险库中写一条带有可选正面的注释。

请求：

{
  "name": "write_note",
  "arguments": {
    "path": "meeting-notes.md",
    "content": "# Team Meeting\n\n## Agenda\n- Project updates\n- Next milestones",
    "frontmatter": {
      "title": "Team Meeting Notes",
      "date": "2023-12-01",
      "tags": ["meetings", "team"]
    }
  }
}

答复：

{
  "message": "Successfully wrote note: meeting-notes.md"
}

list_directory

列出vault中的文件和目录。

请求：

{
  "name": "list_directory",
  "arguments": {
    "path": "Projects"
  }
}

答复：

{
  "path": "Projects",
  "directories": [
    "AI-Tools",
    "Web-Development"
  ],
  "files": [
    "project-template.md",
    "roadmap.md"
  ]
}

delete_note

从保管库中删除注释（需要确认安全性）。

请求：

{
  "name": "delete_note",
  "arguments": {
    "path": "old-draft.md",
    "confirmPath": "old-draft.md"
  }
}

响应（成功）：

{
  "success": true,
  "path": "old-draft.md",
  "message": "Successfully deleted note: old-draft.md. This action cannot be undone."
}

响应（确认失败）：

{
  "success": false,
  "path": "old-draft.md",
  "message": "Deletion cancelled: confirmation path does not match. For safety, both 'path' and 'confirmPath' must be identical."
}

⚠️ 安全注意事项： 这 confirmPath 参数必须与 path 参数以继续删除。这可以防止意外删除。

安全考虑

此MCP服务器实施了多种安全措施来保护您的黑曜石保险库：

路径安全

• 路径横向保护： 所有文件路径都经过验证，以防止在vault外部访问
• 相对路径强制： 路径被规范化并限制在vault目录中
• 符号链接安全： 根据vault边界检查已解析的路径

文件筛选

• 自动排除： .obsidian, .git, node_modules，并过滤系统文件
• 扩展白名单： 仅 .md, .markdown，以及 .txt 默认情况下可以访问文件
• 隐藏文件保护： 点文件和系统目录被自动排除

内容效度

• YAML Frontmatter验证： Frontmatter在写入之前经过解析和验证
• 功能/符号预防： 危险的JavaScript对象被阻止进入frontmatter
• 数据类型检查： 只允许使用安全的数据类型（字符串、数字、数组、对象）

最佳实践

• 最低特权： 服务器仅访问指定的vault目录
• 默认情况下为只读： 考虑对敏感保管库使用只读权限运行
• 建议备份： 在使用写入操作之前，始终备份您的保管库
• 网络隔离： 服务器使用stdio传输（无网络暴露）

什么不受保护

• 文件内容： 服务器可以读取/写入任何允许的文件内容
• 保险库结构： 目录结构对Claude可见
• 文件元数据： 创建时间、文件大小等都是可访问的

⚠️ 重要提示： 仅授予保管库访问受信任的Claude对话的权限。服务器在上述安全边界内提供对笔记的完全读/写访问权限。

建筑

• server.ts -MCP服务器入口点
• src/frontmatter.ts -用灰质处理YAML前体
• src/filesystem.ts -带路径验证的安全文件操作
• src/pathfilter.ts -目录和文件过滤
• src/types.ts -TypeScript类型定义

贡献

1. 复刻仓库
2. 创建要素分支： git checkout -b feature-name
3. 进行更改并添加测试
4. 确保所有测试通过： bun test
5. 提交拉取请求

许可证

麻省理工学院