mcp连接器-for-黑曜石

Name: mcp连接器-for-黑曜石
Author: Prashanth-BC

作者：Prashanth-BC2 星标更新：2025-10-22

安装使用来源：spider==github.com

项目介绍

Obsidian MCP 连接器

通过模型上下文协议（MCP），将您的Obsidian知识库连接到AI助手和自动化工具。此插件实现了您的知识库与兼容MCP客户端（如Claude Code）之间的无缝集成。

为什么使用这个插件？

🎯 智能上下文，最小化令牌

精准而非蛮力

精确检索：无需向AI提供整个知识库，只需精确地定位重要的笔记
查询驱动智能：利用Dataview的强大查询语言，提取您需要的确切内容——不多不少
令牌优化：通过获取相关上下文内容，而不是整个知识库，大幅减少令牌消耗
元数据驱动过滤：利用标签、日期、优先级和自定义字段，以激光般的精度定位信息

区别：与其将1000多条笔记倾倒到AI的上下文窗口中（耗尽令牌并分散注意力），不如询问“显示本季度高优先级项目笔记”，并仅接收10份真正相关的文档。您的AI助手保持专注、响应迅速且成本效益高。

🚀 转型收益

AI驱动的知识编排：将您的知识库从静态存储提升为智能、可查询的知识系统
复杂任务掌握：通过自然对话创建和管理复杂的任务层次结构，带有丰富的元数据
Dataview协同作用：解锁结构化查询的全部能力，无需与复杂的语法搏斗
通用平台支持：在Windows、macOS、Linux和Android上无缝运行——甚至在移动设备上完全独立
隐私优先架构：保持您的知识神圣——一切都在本地运行，无云依赖
经实战考验的可靠性：享受强大的自动重连和优雅的错误处理，确保不间断的工作流程

主要特性

任务管理

✅ 支持Dataview元数据的完整CRUD操作
✅ 优先级级别、截止日期、标签和自定义字段
✅ 自动生成唯一任务ID以便跟踪
✅ 重复任务和事件调度
✅ 通过文本、优先级、标签和日期进行智能搜索
✅ 子任务管理，正确缩进

Dataview集成

✅ 执行TABLE、LIST和TASK查询
✅ 访问页面元数据和内联字段
✅ 使用WHERE/FROM/SORT子句进行复杂过滤
✅ 结构化和Markdown输出格式

知识库操作

✅ 列出、读取和搜索笔记
✅ 文件元数据访问
✅ 基于路径的组织
✅ 全文搜索能力

工作原理

插件使用跨平台工作的统一WebSocket架构：

MCP客户端（Claude Code）←→桥接服务器←→Obsidian插件←→您的知识库
    (HTTP/MCP)                (WebSocket)        (Obsidian API)

桥接服务器本地运行，并在HTTP/MCP和WebSocket协议之间进行转换
Obsidian插件连接到桥接服务器，并将知识库操作暴露为MCP工具
MCP客户端如Claude Code可以通过自然语言与您的知识库交互

支持的平台：

✅ Windows、macOS、Linux（完整的桌面支持）
✅ Android（Termux中独立运行）
⚠️ iOS（需要外部桥接服务器）

快速开始

方案A：自动化安装（推荐）

使用安装脚本自动下载、构建和安装：

# Linux/Mac - 从您的知识库目录
cd /path/to/your/vault
curl -O https://raw.githubusercontent.com/Prashanth-BC/mcp-connector-for-obsidian/main/install.sh
chmod +x install.sh
./install.sh

# 或指定知识库路径
./install.sh /path/to/your/vault

# Windows - 从您的知识库目录
cd C:\path\to\your\vault
curl -O https://raw.githubusercontent.com/Prashanth-BC/mcp-connector-for--obsidian/main/install.cmd
install.cmd

# 或指定知识库路径
install.cmd C:\path\to\your\vault

然后在Obsidian设置 → 社区插件 → MCP连接器中启用插件

方案B：手动安装

# 构建插件
npm ci
npm run build

# 复制到您的知识库
cp -r mcp-connector /path/to/vault/.obsidian/plugins/

在Obsidian设置 → 社区插件 → MCP连接器中启用插件

2. 启动工作区

同时启动桥接服务器和Claude Code：

# Linux/Mac（使用tmux）
cd /path/to/your/vault
./start-mcp-workspace.sh

# Windows（使用Windows终端或单独窗口）
cd C:\path\to\your\vault
start-mcp-workspace.cmd

工作区启动器会自动配置Claude Code与MCP连接。现在您可以向您的AI助手提问：

“列出我所有高优先级的任务”
“在我的笔记中搜索机器学习的参考”
“创建一个任务，在周五之前审查项目计划”
“显示我在项目文件夹中的所有笔记”

使用场景

对于知识工作者

AI辅助研究：让AI助手帮助您探索和连接知识库中的想法
智能任务管理：使用自然语言创建和组织任务
自动化工作流：构建与您的笔记互动的自动化脚本

对于开发者

项目文档：编程式查询项目笔记和技术文档
问题追踪：使用丰富元数据管理开发任务
代码集成：将您的代码与知识库连接起来

对于学生

学习管理：跟踪作业、阅读材料和截止日期
研究组织：高效查询和组织研究笔记
笔记综合：让AI帮助您连接笔记中的概念

文档

架构 - 技术细节和系统设计
设置指南 - 安装和特定平台配置
工具参考 - 所有MCP工具的完整API文档
故障排除 - 常见问题及解决方案

开发

构建

# 安装依赖
npm ci

# 构建一次
npm run build

# 监视更改
npm run watch

测试

npm test

项目结构

src/
├── main.ts                        # 主插件入口点
├── mcp-websocket.ts               # WebSocket传输
├── plugin-bridge.ts               # 工具注册和路由
├── settings.ts                    # 插件设置UI
└── tools/                         # 工具适配器
    ├── mcp-http-ws-bridge.js      # 桥接服务器
    ├── dataview.ts                # Dataview集成
    └── tasks.ts                   # 任务管理

贡献

欢迎贡献！无论是：

🐛 错误报告和修复
✨ 功能请求和实现
📚 文档改进
🧪 测试覆盖率增强

请随时打开问题或提交拉取请求。

许可证

该项目根据GNU通用公共许可证v3.0或更高版本（GPL-3.0-or-later）许可。

总结：

✅ 自由运行、研究、分享和修改代码
✅ 在GPL-3.0-or-later下分发修改版本并附带源代码
❌ 应用与GPL相矛盾的额外限制

对于替代许可安排，请联系讨论双许可选项。

致谢

使用以下工具构建：

Obsidian - 可扩展的知识库
模型上下文协议 - AI集成标准
Dataview - Obsidian的强大查询引擎