金大哥 - obsidian-mcp-server MCP 详情

article

README

🚀 Obsidian MCP 服务器

Obsidian MCP 服务器是一个将 Obsidian 与模型上下文协议（MCP）相连接的服务器，它能实现模板化笔记管理、笔记间链接管理等功能，大大提升笔记的创建、检索与关联效率。

🚀 快速开始

安装依赖

npm install

编译 TypeScript

npm run build

配置环境变量

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
export OBSIDIAN_TEMPLATE_DIR="TEMPLATE"

⚠️ 重要提示

请将 OBSIDIAN_VAULT_PATH 替换为你实际的 Obsidian 保险库路径。

启动服务器

npm start

✨ 主要特性

基本功能

使用模板创建笔记
读取和更新笔记
获取模板列表
管理和搜索标签
搜索文件和目录

链接管理功能（高优先级功能）

在笔记间创建维基链接
检测和修复损坏的链接
分析反向链接并了解图结构
自动生成内容地图（目录笔记）

📦 安装指南

依赖安装

npm install

代码编译

npm run build

环境变量设置

export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
export OBSIDIAN_TEMPLATE_DIR="TEMPLATE"

服务器启动

npm start

💻 使用示例

基础用法

模板创建示例

TEMPLATE/meeting-notes.md 文件内容如下：

---
description: "用于创建会议笔记的模板"
---

# {{title}}

**日期时间**: {{date}} {{time}}
**参会人员**: {{participants}}

## 议程
{{agenda}}

## 会议记录
{{notes}}

## 下次会议前的行动项
{{action_items}}

MCP 调用示例

// 从模板创建笔记
await mcp.callTool('create_note_from_template', {
  templateName: 'meeting-notes',
  variables: {
    title: '项目规划会议',
    participants: '田中、佐藤、山田',
    agenda: '讨论新功能的规格',
    notes: '',
    action_items: ''
  },
  outputPath: 'meetings/2024-01-15-project-planning.md'
});

// 创建笔记间链接
await mcp.callTool('link_notes', {
  sourceNote: 'meetings/2024-01-15-project-planning.md',
  targetNote: 'projects/new-feature.md',
  linkText: '新功能项目',
  insertPosition: 'end'
});

高级用法

链接管理工具使用示例

// 检测损坏的链接
const brokenLinks = await mcp.callTool('find_broken_links');

// 反向链接分析
const backlinks = await mcp.callTool('analyze_backlinks', {
  targetNote: 'concepts/important-concept.md'
});

// 创建内容地图
await mcp.callTool('create_moc', {
  title: '项目相关笔记',
  targetPath: 'index/project-moc.md',
  sourcePattern: 'project',
  groupBy: 'tag',
  includeDescription: true
});

📚 详细文档

MCP 配置方法

Claude Desktop 配置

确认配置文件位置：
- macOS：~/Library/Application Support/Claude/claude_desktop_config.json
- Windows：%APPDATA%\Claude\claude_desktop_config.json
- Linux：~/.config/claude/claude_desktop_config.json
确认项目路径：

pwd

确认 Node.js 路径：

which node

编辑配置文件：在配置文件中添加以下配置：

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

配置示例：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/Users/username/Projects/obsidian-mcp-server/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/username/Documents/MyVault",
        "OBSIDIAN_TEMPLATE_DIR": "TEMPLATE"
      }
    }
  }
}

故障排除（明确指定 Node.js 路径）：

{
  "mcpServers": {
    "obsidian": {
      "command": "/usr/local/bin/node",
      "args": ["/path/to/obsidian-mcp-server/dist/server.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault",
        "OBSIDIAN_TEMPLATE_DIR": "TEMPLATE"
      }
    }
  }
}

⚠️ 重要提示

/path/to/obsidian-mcp-server/dist/server.js 请替换为实际的项目路径

/path/to/your/obsidian/vault 请替换为实际的 Obsidian 保险库路径

/usr/local/bin/node 请替换为 which node 命令确认的 Node.js 路径

重启 Claude Desktop

其他 MCP 客户端配置

如果使用其他 MCP 客户端，请参考以下配置：

命令：node /path/to/obsidian-mcp-server/dist/server.js
环境变量：
- OBSIDIAN_VAULT_PATH：Obsidian 保险库路径
- OBSIDIAN_TEMPLATE_DIR：模板目录名称

可用工具

1. create_note_from_template

使用模板创建 Obsidian 笔记。 | 参数 | 详情 | |------|------| | templateName（必需） | TEMPLATE 文件夹内的模板名称（无 .md 扩展名） | | variables（必需） | 用于替换模板内变量的对象 | | outputPath（必需） | 笔记的保存路径（相对于保险库的路径） | | overwrite（可选） | 是否覆盖现有文件（默认：false） |

2. list_templates

获取 TEMPLATE 文件夹内可用的模板列表。 | 参数 | 详情 | |------|------| | 无 | 无 |

3. read_note

读取 Obsidian 笔记的内容。 | 参数 | 详情 | |------|------| | notePath（必需） | 笔记的路径（相对于保险库的路径） |

4. update_note

更新 Obsidian 笔记的内容。 | 参数 | 详情 | |------|------| | notePath（必需） | 笔记的路径（相对于保险库的路径） | | content（必需） | 新的笔记内容 |

5. list_tags

列出 Obsidian 保险库内的所有标签。 | 参数 | 详情 | |------|------| | 无 | 无 |

6. rename_tag

批量重命名 Obsidian 保险库内的标签。 | 参数 | 详情 | |------|------| | oldTag（必需） | 更改前的标签名称（带 # 或不带 #） | | newTag（必需） | 更改后的标签名称（带 # 或不带 #） |

7. search_files

在 Obsidian 保险库内搜索文件和目录。 | 参数 | 详情 | |------|------| | searchPath（可选） | 搜索开始的路径（相对于保险库的路径，省略时为根目录） | | pattern（可选） | 搜索模式（文件名的一部分，省略时为全部） |

链接管理工具（高优先级功能）

8. link_notes

在笔记间创建维基链接。 | 参数 | 详情 | |------|------| | sourceNote（必需） | 链接源笔记的路径（相对于保险库的路径） | | targetNote（必需） | 链接目标笔记的路径（相对于保险库的路径） | | linkText（可选） | 显示文本（省略时为文件名） | | insertPosition（可选） | 插入位置（'end'、'cursor' 或行号，默认：'end'） |

功能：

检查文件是否存在
检测并警告重复链接
解析相对路径
以维基链接格式 [[目标|显示文本]] 插入

9. find_broken_links

检测并修复损坏的链接。 | 参数 | 详情 | |------|------| | 无 | 无 |

功能：

支持维基链接 [[]] 和 Markdown 链接 []()
通过模糊搜索提供修复候选
考虑大小写、空格和特殊字符的差异
显示行号和周边上下文

返回值：

{
  "brokenLinks": [
    {
      "sourceFile": "notes/example.md",
      "linkText": "缺失的笔记",
      "targetPath": "missing-note",
      "lineNumber": 15,
      "suggestions": ["similar-note", "missing-note-backup"]
    }
  ],
  "totalCount": 1
}

10. analyze_backlinks

分析反向链接并了解图结构。 | 参数 | 详情 | |------|------| | targetNote（必需） | 分析目标笔记的路径（相对于保险库的路径） |

功能：

检测指向指定笔记的反向链接
提取链接周边的上下文
识别相关笔记
计算流行度和中心性指标