AI导哈

笔记管理服务器

一个为Obsidian知识库提供程序化访问的MCP服务器，支持读取、写入、编辑和搜索Markdown笔记。

  • by Nattie-Nkosi
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Nattie-Nkosi/Obsidian-MCP-server

使用说明

黑曜石MCP服务器

一个模型上下文协议（MCP）服务器，提供对黑曜石保险库的编程访问。此服务器使AI助手和其他MCP客户端能够读取、写入、编辑和搜索黑曜石保险库中的标记笔记。

遵循可维护性和可扩展性的关注点分离原则，采用干净的模块化架构构建。

特性

  • 阅读笔记：访问单个笔记或列出vault中的所有笔记
  • 写笔记：创建新笔记或覆盖现有笔记
  • 编辑笔记：查找并替换注释中的文本
  • 附加内容：将内容添加到现有笔记的末尾
  • 搜索：搜索包含特定文本的笔记（不区分大小写）
  • MCP资源：将所有保管库笔记作为MCP资源公开 obsidian:// URI
  • 路径安全：内置目录遍历保护，限制对vault的访问
  • 清洁建筑：模块化代码库，关注点明确分离
  • 类型安全：完全使用TypeScript类型以提高可靠性

安装

npm install

配置

创建一个 .env 项目根目录中的文件：

OBSIDIAN_VAULT_PATH=C:\path\to\your\obsidian\vault

如果未指定，服务器将默认为当前工作目录。

用法

构建并运行

# Build the TypeScript project
npm run build

# Run the compiled server
npm start

发展

# Run directly from TypeScript source
npm run dev

项目结构

代码库遵循模块化架构，关注点明确分离：

src/
├── index.ts              # Entry point - starts the server
├── server.ts             # Server initialization and request handler setup
├── config.ts             # Configuration and environment variables
├── handlers/
│   ├── resources.ts      # MCP resource handlers (list/read notes)
│   └── tools.ts          # MCP tool handlers and definitions
└── utils/
    ├── validation.ts     # Path validation and argument checking
    └── filesystem.ts     # File system operations

建筑亮点

  • 模块化设计：每个模块都有一个明确的责任
  • 处理器分离：资源和工具在单独的模块中处理
  • 可重复使用的实用程序：将常见操作抽象为实用函数
  • 集中验证：专用模块中的安全和输入验证
  • 易于测试：隔离功能，便于更好的单元测试
  • 可维护性：清晰的代码组织使更新变得简单

MCP客户端集成

此服务器使用stdio传输，可以与任何MCP客户端集成。将以下内容添加到MCP客户端配置中：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "C:\\path\\to\\your\\obsidian\\vault"
      }
    }
  }
}

客户端集成示例

克劳德桌面 (~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/Users/username/projects/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/username/Documents/ObsidianVault"
      }
    }
  }
}

视窗 (%APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["C:\\projects\\obsidian-mcp-server\\dist\\index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "C:\\Users\\username\\Documents\\ObsidianVault"
      }
    }
  }
}

可用工具

write_note

创建新笔记或覆盖现有笔记。

参数：

  • path （string）：保险库内的相对路径（例如。， folder/note.md)
  • content （string）：降价内容

edit_note

通过替换特定文本来编辑现有注释。

参数：

  • path （string）：音符的相对路径
  • find （string）：要查找的文本
  • replace （string）：要替换的文本

append_note

将内容附加到现有注释中。

参数：

  • path （string）：音符的相对路径
  • content （string）：要附加的内容

read_note

阅读特定笔记的内容。

参数：

  • path （string）：音符的相对路径

list_notes

列出vault中的所有注释及其路径。

参数： 无

search_notes

搜索包含特定文本的笔记（不区分大小写）。

参数：

  • query （string）：要搜索的文本

资源

vault中的所有标记文件都作为MCP资源公开，其中包括：

  • 统一资源标识符: obsidian://{relative-path}
  • mime类型: text/markdown
  • 名字：文件名

安全

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

  • 路径验证：所有文件操作都会验证路径，以防止目录遍历攻击
  • 保险库限制：操作严格限于配置的vault路径
  • 输入验证：在处理之前验证工具参数
  • 错误处理：通过信息丰富的错误消息进行优雅的错误处理

技术细节

技术

  • 语言：TypeScript（ESM模块）
  • MCP-SDK: @modelcontextprotocol/sdk v0.6.1+
  • 运输：stdio（标准输入/输出）
  • Node.js：为现代Node.js构建，具有ES2022+功能

MCP协议实现

此服务器实现了模型上下文协议规范：

  • 资源：使用自定义将vault笔记显示为可读资源 obsidian:// URI
  • 工具：提供六种工具用于完整的笔记管理
  • 标准运输：通过标准输入/输出进行通信，便于集成

发展

要使用新功能扩展服务器，请执行以下操作：

  1. 添加新工具：在中定义工具模式 src/handlers/tools.ts 并实现处理程序
  2. 添加实用程序：在中创建可重用函数 src/utils/
  3. 扩展验证：在中添加新的验证规则 src/utils/validation.ts
  4. 修改资源：更新中的资源处理程序 src/handlers/resources.ts

模块化架构使添加新功能变得容易，而不会影响现有功能。

贡献

欢迎投稿！干净的架构和TypeScript类型使其易于理解和扩展代码库。

许可证

麻省理工学院

作者

纳蒂 谢谢

相关 MCP