Another Bloated Obsidian MCP Server

另一个臃肿的黑曜石MCP服务器

\[！小心\] 🔴🔴🔴 实验项目-不用于生产🔴🔴🔴 这是一个实验项目，主要是通过使用Claude Code的人工智能辅助开发创建的，只需要最少的人为干预。它仅用于测试和学习目的。 本项目不得用于： - 生产环境 - 关键数据或重要保管库 - 数据完整性至关重要的任何场景 使用风险自负。代码可能包含错误、安全漏洞或意外行为。 支持通知： 该项目可能不会因第三方报告的错误或问题而受到关注。如果你有兴趣贡献或报告问题，你可能不会得到回应，因为这个项目可能不会长期维护。然而，在实验阶段之后，这种情况可能会改变。

______________________________________________________________________

一种模型上下文协议（MCP）服务器，为AI助手提供对黑曜石金库的安全访问。无需运行Obsidian即可读取、写入、搜索和管理笔记。

特性

• 直接文件系统访问 -无黑曜石跑步
• 多保险库支持 -同时管理多个保管库
• 可配置的工具组 -仅启用所需的功能
• 完整的CRUD操作 -创建、阅读、更新、删除笔记
• YAML前体 -解析和操作笔记元数据
• 标签管理 -按标签添加、删除和搜索
• 链接分析 -反向链接、外链接、孤立链接、断开链接、链接图
• 每日笔记 -创建和管理每日日记账分录
• 模板 -应用带有变量替换的模板
• 黑曜石基底 -基于过滤器查询动态笔记视图
• 批量操作 -高效处理多个笔记
• 附件跟踪 -列出并查找未使用的附件
• 备份系统 -创建和恢复笔记备份
• 安全第一 -路径遍历保护，防止符号链接逃逸

需求

• Node.js 18+
• npm或纱线

安装

# Clone the repository
git clone https://github.com/yourusername/obsidian-mcp-server.git
cd obsidian-mcp-server

# Install dependencies
npm install
# or
yarn install

# Build (optional - can run directly with tsx)
npm run build

快速开始

# Start the server with a vault
npm start /path/to/your/vault

# With specific tool groups
npm start /path/to/your/vault --tools=vault,notes,search

# With a custom vault name
npm start /path/to/your/vault my-vault

配置

选项1:克劳德代码CLI（推荐）

# Add the MCP server
claude mcp add obsidian \
  --transport stdio \
  --scope user \
  -- npx tsx /path/to/obsidian-mcp-server/src/index.ts /path/to/vault

# With specific tool groups
claude mcp add obsidian \
  --transport stdio \
  --scope user \
  -- npx tsx /path/to/obsidian-mcp-server/src/index.ts /path/to/vault --tools=vault,notes,search

范围选项：

• user -在所有项目中都可用（保存在 ~/.claude.json)
• local -仅限当前项目
• project -与团队共享（保存在 .mcp.json)

有用的命令：

claude mcp list          # List configured servers
claude mcp get obsidian  # View server details
claude mcp remove obsidian  # Remove server

选项2：手动配置

编辑 ~/.claude.json:

{
  "mcpServers": {
    "obsidian": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/obsidian-mcp-server/src/index.ts",
        "/path/to/your/vault",
        "--tools=vault,notes,search"
      ]
    }
  }
}

选项3:Claude桌面应用程序

在以下位置编辑配置文件 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "tsx",
        "/path/to/obsidian-mcp-server/src/index.ts",
        "/path/to/your/vault",
        "--tools=vault,notes,search"
      ]
    }
  }
}

工具组

特殊值：

• all -启用所有工具组（默认）
• none -禁用所有工具（用于测试）

配置示例

只读访问

--tools=vault,notes,search

无需修改注释即可安全探索。

日常生产力

--tools=vault,notes,search,daily,tags

快速捕获、每日笔记和标签组织。

知识分析

--tools=vault,notes,search,links,tags

探索联系，找到孤儿，分析知识图谱。

内容创作

--tools=vault,notes,search,templates,frontmatter

从模板创建笔记，管理元数据。

完全访问权限

--tools=all

所有功能均已启用。

多保险库设置

创建 ~/.obsidian-mcp/config.json:

{
  "vaults": {
    "personal": "/Users/you/Obsidian/Personal",
    "work": "/Users/you/Obsidian/Work",
    "research": "/Users/you/Obsidian/Research"
  },
  "defaultVault": "personal"
}

使用以下命令在保管库之间切换 set_active_vault 工具。

环境变量

CLI 参考

# Show help
npm start -- --help

# Start with vault
npm start /path/to/vault [vault-name] [--tools=groups]

# Examples
npm start /path/to/vault                    # All tools
npm start /path/to/vault my-vault           # With custom name
npm start /path/to/vault --tools=vault,notes  # Specific groups

故障排除

服务器未连接

1. 验证vault路径是否存在并且是绝对路径
2. 检查Node.js版本： node --version （要求18+）
3. 手动测试： npm start /path/to/vault
4. 对于克劳德代码：使用 /mcp 检查状态和错误
5. 对于Claude Desktop：检查登录 ~/Library/Logs/Claude/mcp*.log

“工具X未启用”错误

您尝试使用的工具不在您启用的组中。检查你的 --tools 配置并添加所需的组。

权限错误

确保运行MCP服务器的用户具有对vault目录的读/写访问权限。

未找到路径

• 使用绝对路径，而不是相对路径
• 确保保险库包含 .obsidian 文件夹
• 检查路径中的拼写错误

发展

# Development mode (auto-reload)
npm run dev

# Build
npm run build

# Type check
npx tsc --noEmit

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

文档

• api参考 -完整的工具文档
• 建筑 -系统设计
• 配置 -所有配置选项
• 安全 -安全模型
• 错误代码 -错误参考
• 贡献 -发展指南

安全

此服务器实施了多种安全措施：

• 路径验证 -防止路径遍历攻击
• Symlink保护 -阻止符号链接转义尝试
• 输入验证 -所有输入均已Zod模式验证
• 保留名称阻止 -防止系统文件冲突

看 安全.md 了解详情。

灵感

这个项目的灵感来自 mcp黑曜岩.

许可证

麻省理工学院