AI导哈

Obsidian MCP服务器

一个基于TypeScript的模型上下文协议（MCP）服务器，为AI助手提供对Obsidian保险库的安全访问，支持多保险库、可配置文件访问和全面的Markdown操作。

  • by dalager
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 dalager/obsidian-mcp

使用说明

黑曜石MCP服务器

基于TypeScript的模型上下文协议（MCP）服务器，为AI助手提供对黑曜石金库的安全访问。在本地运行，支持多个保管库、可配置的文件访问和全面的标记操作。

特性

  • 多保险库支持：通过单独配置访问多个黑曜石保险库
  • 安全文件操作：路径验证、大小限制和可配置范围限制
  • YAML前端编辑器：解析和操作markdown文件中的frontmatter
  • 文件类型筛选：支持 .md, .png, .pdf，以及可配置的附加扩展
  • 内容搜索：在带有上下文的markdown文件中进行基本文本搜索
  • 交叉平台的：适用于Windows、macOS和Linux

安装

全局安装（推荐）

npm install -g obsidian-mcp-server

地方发展

git clone <repository-url>
cd obsidian-mcp-server
npm install
npm run build

配置

创建一个 config.json 用于定义vault设置的文件：

{
  "vaults": [
    {
      "name": "main",
      "path": "/path/to/your/obsidian-vault",
      "allowedPaths": [
        "notes/",
        "projects/"
      ]
    },
    {
      "name": "work",
      "path": "/path/to/work-vault"
    }
  ],
  "fileExtensions": [
    ".md",
    ".png", 
    ".pdf",
    ".txt"
  ],
  "maxFileSize": "10MB",
  "logLevel": "info",
  "logToFile": true,
  "verifyVaultsOnStartup": true
}

配置选项

  • 拱顶：vault配置数组
    • name：保险库的唯一标识符
    • path：vault目录的绝对路径
    • allowedPaths：（可选）用于限制访问的子目录路径数组
  • 文件扩展名：允许的文件扩展名数组（默认值： .md, .png, .pdf)
  • 最大文件大小：读取的最大文件大小（默认值： 10MB)
  • logLevel：记录详细程度（默认值： info)-选项： error, warn, info, debug
  • logToFile：启用基于文件的日志记录（默认值： true)-创建登录 logs/ 目录
  • 验证Vault启动：启动时验证vault访问权限并记录顶部文件夹（默认值： true)

用法

命令行

# With config file
obsidian-mcp-server --config /path/to/config.json

# With config file and specific log level
obsidian-mcp-server --config /path/to/config.json --log-level debug

# With default configuration (uses current directory)
obsidian-mcp-server

MCP客户端集成

添加到您的MCP客户端配置中（例如，Claude Desktop）：

{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "args": ["--config", "/path/to/your/config.json"]
    }
  }
}

如果在本地运行

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js", "--config", "/path/to/obsidian-mcp-server/config/config.json"]
    }
  }
}

MCP工具

服务器为AI助手提供以下工具：

read_file

从markdown文件读取内容或从二进制文件读取元数据。

{
  "vault_name": "main",
  "file_path": "notes/example.md",
  "include_content": true,
  "include_frontmatter": true
}

write_file

使用可选的frontmatter创建或更新markdown文件。

{
  "vault_name": "main",
  "file_path": "notes/new-note.md",
  "content": "# New Note\n\nContent here...",
  "frontmatter": {
    "title": "My New Note",
    "tags": ["example", "new"]
  },
  "create_directories": true
}

list_files

使用筛选列出vault目录中的文件。

{
  "vault_name": "main",
  "directory_path": "notes",
  "include_metadata": false
}

search_content

在markdown文件中搜索文本。

{
  "vault_name": "main",
  "query": "search term",
  "directory_path": "notes",
  "case_sensitive": false,
  "whole_word": false,
  "max_results": 50
}

get_metadata

获取包括frontmatter在内的文件元数据，但不包括完整内容。

{
  "vault_name": "main",
  "file_path": "notes/example.md"
}

发展

脚本

# Build the project
npm run build

# Development with watch mode
npm run dev

# Run tests
npm run test
npm run test:watch
npm run test:coverage

# Linting and formatting
npm run lint
npm run lint:fix
npm run format
npm run format:check

项目结构

src/
├── config/           # Configuration loading and validation
├── obsidian/         # Vault operations and metadata parsing
├── tools/            # MCP tool implementations
├── server.ts         # Main MCP server
└── index.ts          # CLI entry point

测试

该项目包括综合测试：

  • 所有核心功能的单元测试
  • 使用模拟保险库进行集成测试
  • 90%+测试覆盖率目标
  • 跨平台兼容性测试

运行测试：

npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage report

安全

  • 路径验证：防止目录遍历攻击
  • 作用域限制：每个保险库可配置的允许路径
  • 文件大小限制：防止读取过大的文件
  • 扩展过滤：仅处理指定的文件类型
  • 只读二进制文件：二进制文件仅返回元数据

故障排除

常见问题

  1. 权限错误：确保服务器具有对vault目录的读/写访问权限
  2. 路径问题：在配置中使用绝对路径
  3. 文件大小错误：调整 maxFileSize 如果需要更大的文件
  4. 扩展错误：向添加所需的扩展名 fileExtensions 数组

调试模式

启用详细日志记录：

# Using command line option
obsidian-mcp-server --config config.json --log-level debug

# Or set in config.json
{
  "logLevel": "debug",
  "vaults": [...],
  ...
}

可用日志级别： error, warn, info, debug

日志记录功能

服务器使用Winston进行全面的日志记录，具有以下功能：

  • 控制台的日志：输出到stderr的所有日志（着色以提高可读性）
  • 文件记录：存储在中的持久日志 logs/ 目录
    • combined.log：所有日志级别（旋转，最大5MB，保留5个文件）
    • error.log：仅错误级别日志（旋转，最大5MB，保留5个文件）
    • exceptions.log：无异常
    • rejections.log：未经处理的promise拒绝

原木结构：每个日志条目都包括时间戳、级别、消息和结构化元数据 性能计时：操作包括性能监控的执行时间 运营跟踪：每个工具执行都会获得一个唯一的操作ID进行跟踪

通过设置禁用文件日志记录 "logToFile": false 在您的配置中。

保险库验证

启动时，服务器会自动验证vault访问权限，并记录每个vault中排名前10位的文件夹（按文件数）。这有助于确认：

  • 保险库路径是可访问的
  • 文件权限正确
  • 预期的内容结构已存在

验证输出示例：

[INFO] Starting vault verification process
[INFO] Verifying vault access {"vaultName":"main","path":"/path/to/vault"}
[INFO] Top folders in vault {"vaultName":"main","folders":[
  {"name":"notes","path":"notes","fileCount":45},
  {"name":"projects","path":"projects","fileCount":23},
  {"name":"archive","path":"archive","fileCount":12}
]}
[INFO] Vault verification completed {"vaultName":"main","foldersFound":8,"durationMs":156}

通过设置禁用验证 "verifyVaultsOnStartup": false 在您的配置中。

许可证

麻省理工学院

贡献

  1. 分叉存储库
  2. 创建要素分支
  3. 添加新功能的测试
  4. 确保所有测试通过
  5. 提交拉取请求

支持

相关 MCP