星战科技xingzhan.cloud
返回市场
麦克佩斯黑曜石

麦克佩斯黑曜石

作者：bitbonsai160 星标更新：2025-10-24
安装使用来源：spider==github.com

项目介绍

<div align="center"> <img width="256" height="256" alt="image" src="https://gips1.baidu.com/it/u=519038806,3732820138&fm=3081&app=3081&f=PNG?w=256&h=256" /> </div>

MCP-Obsidian

使用模型上下文协议（MCP）标准的通用AI桥接器，适用于Obsidian知识库。连接任何兼容MCP的AI助手到您的知识库——支持Claude、ChatGPT以及未来的AI工具。此服务器提供安全的读写访问权限，同时防止YAML前缀损坏。

<div align="center">

https://mcp-obsidian.org

</div> <div align="center">

GitHub Stars npm version GitHub Sponsors Ko-Fi Liberapay

</div>

全面兼容性

与任何兼容MCP的AI助手配合工作，包括Claude Desktop、Claude Code、ChatGPT Desktop（企业版及以上）、IntelliJ IDEA 2025.1+、Cursor IDE、Windsurf IDE以及未来采用MCP标准的AI平台。

https://github.com/user-attachments/assets/657ac4c6-1cd2-4cc3-829f-fd095a32f71c

快速开始（5分钟）

  1. 安装Node.js运行时：

    # 从 https://nodejs.org 下载（v18.0.0或更高版本）
# 或者使用包管理器如nvm、brew、apt等

  2. 测试服务器：

    如果使用已发布的包：

    npx @modelcontextprotocol/inspector npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault

  3. 配置您的AI客户端：

    Claude Desktop - 将以下内容复制到 claude_desktop_config.json 中：

    {
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"]
    }
  }
}

    Claude Code - 将以下内容复制到 ~/.claude.json 中：

    {
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"],
      "env": {}
    }
  }
}

    将 /path/to/your/vault 替换为您实际的Obsidian知识库路径。

    对于其他平台，请参阅下面的 详细配置指南。

  4. 使用您的AI进行测试：

    • "列出我的Obsidian知识库中的文件"
    • "阅读名为'project-ideas.md'的笔记"
    • "创建一个带有今天日期的新笔记"

成功指标： 您的AI应该能够列出文件并从您的知识库中读取笔记。

为什么选择MCP-Obsidian？

全面的AI兼容性

基于开放的模型上下文协议标准，MCP-Obsidian不受限于任何单一的AI提供商。随着更多AI助手采用MCP，您对此工具的投资价值会增加。目前它支持Claude和ChatGPT，未来将支持所有新兴的AI工具。

保护您的知识库

无需等待每个AI公司构建Obsidian集成，MCP-Obsidian提供了一个通用适配器，适用于任何兼容MCP的助手。一种工具，无限可能。

开放标准，无锁定

MCP是一个开放协议。您不会被绑定到任何特定的供应商或平台。您的笔记仍然属于您，可以通过任何兼容的AI助手访问。

特点

  • ✅ 使用gray-matter进行安全的前缀解析和验证
  • ✅ 路径过滤以排除.obsidian目录和其他系统文件
  • ✅ 完整的MCP工具包：涵盖所有知识库操作的11种方法
    • 文件操作：read_note，write_note，delete_note，move_note
    • 目录操作：list_directory
    • 批量操作：read_multiple_notes
    • 搜索：search_notes，支持内容和前缀搜索
    • 元数据：get_frontmatter，update_frontmatter，get_notes_info
    • 标签管理：manage_tags（添加、删除、列出）
  • ✅ 写入模式：overwrite，append，prepend，用于灵活的内容编辑
  • ✅ 标签管理：在笔记中添加、删除和列出标签
  • ✅ 安全删除，需要确认以防止意外删除
  • ✅ 自动路径修剪，处理输入中的空白
  • ✅ TypeScript支持，使用Node.js运行时（使用tsx执行）
  • ✅ 全面的错误处理和验证
  • ✅ 优化响应：通过最小化字段名称和紧凑JSON，响应大小减少40-60%（v0.6.3+）
  • ✅ 可选美化打印：设置prettyPrint: true以便于人类调试
  • ✅ 性能优化：没有不必要的令牌消耗，适合大型知识库
  • ✅ 零依赖：不需要Obsidian插件，适用于任何知识库结构
  • ✅ 智能链接处理：内部链接和引用的智能处理

前提条件

  • Node.js 运行时（v18.0.0或更高版本）
  • 一个Obsidian知识库（包含.md文件的本地目录）
  • 兼容MCP的AI客户端（Claude Desktop，ChatGPT Desktop，Claude Code等）

安装

终端用户（推荐）

无需安装！使用npx直接运行：

npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault

开发者

  1. 克隆此仓库
  2. 使用npm安装依赖项：
npm install
  1. 使用MCP检查器进行本地测试：
npx @modelcontextprotocol/inspector npm start /path/to/your/vault

小贴士：使用MCP检查器测试所有服务器功能，然后再配置AI客户端：

# 全局安装以方便访问
npm install -g @modelcontextprotocol/inspector

# 测试任何知识库
mcp-inspector npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault

使用

运行服务器

终端用户：

npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/obsidian/vault

开发者：

npm start /path/to/your/obsidian/vault

AI客户端配置

Claude Desktop

添加到您的Claude Desktop配置文件中：

单个知识库：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@mauricio.wolff/mcp-obsidian@latest", "/Users/yourname/Documents/MyVault"]
    }
  }
}

多个知识库：

{
  "mcpServers": {
    "obsidian-personal": {
      "command": "npx",
      "args": ["@mauricio.wolff/mcp-obsidian@latest", "/Users/yourname/Documents/PersonalVault"]
    },
    "obsidian-work": {
     - "command": "npx",
      "args": ["@mauricio.wolff/mcp-obsidian@latest", "/Users/yourname/Documents/WorkVault"]
    }
  }
}

配置文件位置：

  • macOS：~/Library/Application Support/Claude/claude_desktop_config.json
  • Windows：C:\Users\{username}\AppData\Roaming\Claude\claude_desktop_config.json
  • Linux：~/.config/Claude/claude_desktop_config.json

您也可以通过Claude Desktop → 设置 → 开发者 → 编辑配置来访问

ChatGPT Desktop

要求：ChatGPT企业版、教育版或团队订阅（不适用于个人Plus用户）

ChatGPT通过深度研究和开发者模式使用MCP。配置是通过ChatGPT界面完成的：

  1. 访问ChatGPT开发者模式（测试功能）
  2. 通过内置的MCP客户端配置MCP服务器
  3. 为您的组织创建自定义连接器

注意：ChatGPT Desktop的MCP集成目前仅限于企业订阅，并且使用不同于基于文件配置的设置过程。

Claude Code

Claude Code使用.claude.json配置文件：

用户范围（推荐）： 编辑~/.claude.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"],
      "env": {}
    }
  }
}

项目范围： 编辑项目中的.claude.json或添加到项目部分：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "obsidian": {
          "command": "npx",
          "args": ["@mauricio.wolff/mcp-obsidian@latest", "/path/to/your/vault"]
        }
      }
    }
  }
}

使用Claude Code CLI：

claude mcp add obsidian --scope user npx @mauricio.wolff/mcp-obsidian /path/to/your/vault

Goose Desktop

在Goose Desktop设置中，点击添加自定义扩展，并在命令字段中添加：

npx @mauricio.wolff/mcp-obsidian@latest /path/to/your/vault

其他MCP兼容客户端（2025）

确认MCP支持：

  • IntelliJ IDEA 2025.1+ - 原生MCP客户端支持
  • Cursor IDE - 内置MCP兼容性
  • Windsurf IDE - 完整MCP集成
  • Zed, Replit, Codeium, Sourcegraph - 正在开发中
  • Microsoft Copilot Studio - 原生MCP支持，一键服务器连接

大多数现代MCP客户端使用类似的JSON配置模式。请参考您特定客户端的文档获取确切的设置说明。

示例

向您的AI助手询问笔记：

  • "我的Obsidian知识库中有哪些文件？"
  • "阅读名为'project-ideas.md'的笔记"
  • "显示所有标题中包含'AI'的笔记"

让您的AI助手帮助管理笔记：

  • "创建一个名为'meeting-notes.md'的新笔记，并在前缀中添加今天的日期"
  • "将今天的日记条目追加到我的日常笔记中"
  • "在待办事项列表的开头添加紧急任务"
  • "给我的任务笔记添加'task'和'urgent'标签"
  • "列出我研究笔记中的所有标签"
  • "从已完成的文章中移除'draft'标签"
  • "列出'Projects'文件夹中的所有markdown文件"
  • "删除旧草稿笔记'draft-ideas.md'（需确认）"

高级用例：

  • 知识合成："总结过去一个月内所有标记为'machine-learning'的研究笔记"
  • 项目管理："更新所有项目笔记的状态为'已完成'，并添加今天的日期"
  • 内容分析："查找所有提到'API设计'的笔记，并创建一份综合指南"
  • 智能标签："审查未标记的笔记，并根据内容建议适当的标签"

故障排除

常见问题

"命令未找到：npx"

  • 解决方案：从nodejs.org安装Node.js运行时
  • 替代方案：全局安装：npm install -g @mauricio.wolff/mcp-obsidian

"用法：node server.ts /path/to/vault"

  • 原因：未提供知识库路径
  • 解决方案：指定知识库目录的完整路径

"权限不足"错误

  • 原因：文件系统权限不足
  • 解决方案：确保知识库目录对您的用户可读写

"不允许路径遍历"

  • 原因：尝试访问知识库之外的文件
  • 解决方案：所有文件路径必须相对于知识库根目录

AI客户端无法识别服务器

  1. 检查配置文件路径是否正确对应您的操作系统
  2. 确保JSON语法有效（使用JSON验证器）
  3. 在更改配置后重启您的AI客户端
  4. 检查您的AI客户端日志中的错误消息
  5. 验证您的AI客户端是否支持MCP（模型上下文协议）

".obsidian文件仍然显示"

  • 预期结果：路径过滤器自动排除.obsidian/**模式
  • 如果仍然看到它们：过滤器按设计工作以保证安全性

调试模式

带错误日志运行：

npx @mauricio.wolff/mcp-obsidian /path/to/vault 2>debug.log

获取帮助

  • 在GitHub上打开一个问题
  • 包括您的操作系统、Node.js版本和错误消息
  • 提供知识库目录结构（不含敏感内容）

测试

运行测试套件：

npm test

API 方法

read_note

从知识库中读取带有解析前缀的笔记。

请求：

{
  "name": "read_note",
  "arguments": {
    "path": "project-ideas.md",
    "prettyPrint": false
  }
}

响应（优化了令牌）：

{"fm":{"title":"Project Ideas","tags":["projects","brainstorming"],"created":"2023-01-15T10:30:00.000Z"},"content":"# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"}

响应（prettyPrint: true）：

{
  "fm": {
    "title": "Project Ideas",
    "tags": ["projects", "brainstorming"],
    "created": "2023-01-15T10:30:00.000Z"
  },
  "content": "# Project Ideas\n\n## AI Tools\n- MCP server for Obsidian\n- Voice note transcription\n\n## Web Apps\n- Task management system"
}

write_note

将笔记写入知识库，可选前缀和写入模式。

写入模式：

  • overwrite（默认）：替换整个文件内容
  • append：将内容添加到现有文件末尾
  • prepend：将内容添加到现有文件开头

请求（覆盖）：

{
  "name": "write_note",
  "arguments": {
    "path": "meeting-notes.md",
    "content": "# Team Meeting\n\n## Agenda\n- Project updates\n- Next milestones",
    "frontmatter": {
      "title": "Team Meeting Notes",
      "date": "2023-12-01",
      "tags": ["meetings", "team"]
    },
    "mode": "overwrite"
  }
}

请求（追加）：

{
  "name": "write_note",
  "arguments": {
    "path": "daily-log.md",
    "content": "\n\n## 3:00 PM Update\n- Completed project review\n- Started new feature",
    "mode": "append"
  }
}

响应：

{
  "message": "成功写入笔记：meeting-notes.md（模式：覆盖）"
}

list_directory

列出知识库中的文件和目录。

请求：

{
  "name": "list_directory",
  "arguments": {
    "path": "Projects",
    "prettyPrint": false
  }