Obsidian MCP Server

🚀 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 配置

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

pwd

3. 确认 Node.js 路径：

which node

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

{
  "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 路径

5. 重启 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 笔记。

2. list_templates

获取 TEMPLATE 文件夹内可用的模板列表。

3. read_note

读取 Obsidian 笔记的内容。

4. update_note

更新 Obsidian 笔记的内容。

5. list_tags

列出 Obsidian 保险库内的所有标签。

6. rename_tag

批量重命名 Obsidian 保险库内的标签。

7. search_files

在 Obsidian 保险库内搜索文件和目录。

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

8. link_notes

在笔记间创建维基链接。

功能：

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

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": "important-concept.md",
  "backlinks": [
    {
      "sourceFile": "notes/research.md",
      "context": "这个概念被称为[[important-concept]]",
      "linkType": "wiki"
    }
  ],
  "relatedNotes": ["notes/research.md"],
  "metrics": {
    "popularity": 5,
    "centrality": 0.1
  }
}

11. create_moc

自动生成内容地图（目录笔记）。

功能：

• 通过模式匹配选择文件
• 按标签或文件夹分组
• 自动从 YAML frontmatter 中提取描述
• 以维基链接格式生成目录

生成示例：

# 项目相关笔记

*此内容地图是自动生成的 - 2024-01-15*

## #project
- [[project-planning|项目规划]] - 新功能的规划和设计
- [[project-timeline|项目时间表]] - 开发时间表和里程碑

## #development  
- [[api-design|API 设计]] - RESTful API 的规格说明
- [[database-schema|数据库设计]] - 表结构和关系

📄 许可证

本项目采用 MIT 许可证，详情请参阅 LICENSE 文件。