Obsidian MCP Server

Obsidian MCP Server

English | 中文文档（机翻）

此 Obsidian 插件会运行本地 MCP（Model Context Protocol）服务，让外部应用（如 AI 助手、脚本或其他工具）通过标准化接口与您的 Obsidian 知识库交互。

功能

• 本地 MCP 服务： 在可配置的端口上运行基于 SSE 的 MCP 服务。
• 知识库索引与语义搜索：
  • 将 Markdown 笔记内容索引到 Orama 向量数据库中。
  • 使用可配置的 OpenAI 兼容嵌入模型（例如 OpenAI，或通过兼容端点使用本地 Ollama 模型）生成嵌入向量。
  • 支持配置文本分块参数（大小、重叠长度、分隔符）。
  • 支持使用 .gitignore 语法排除特定文件或模式，使其不参与索引。
• Obsidian 集成：
  • 命令： 在 Obsidian 命令面板中提供以下命令：
    • 启动/停止 MCP 服务。
    • 重新索引整个知识库（可能耗时较长，具体成本取决于嵌入服务提供商）。
    • 手动保存向量数据库索引。
  • 设置选项卡： 提供专用设置面板，可配置：
    • 服务端口和自动启动行为。
    • 嵌入服务提供商详情（API 端点、模型名称、API 密钥）。
    • 索引时的文件排除模式。
    • 分块参数。
    • 验证嵌入服务提供商的连接。
  • 功能区图标： 在 Obsidian 功能区中添加状态图标，指示 MCP 服务正在运行还是已停止。
  • 国际化： 根据 Obsidian 的语言设置，支持英语和中文界面。

MCP 工具

• simple_vector_search：使用向量嵌入对笔记进行语义搜索。
• count_entries：统计 Orama 数据库中的已索引笔记和分块数量。
• list_files：列出指定目录中的文件和文件夹。
• read_file：读取指定文件的内容。
• create_file：创建新文件。
• edit_file：编辑现有文件中的指定行范围。
• delete_file：删除文件。
• create_folder：创建文件夹。
• delete_folder：删除文件夹。

待办事项

• 支持多语言（英语、中文）
• 提供基本的文件/文件夹操作工具（创建、读取、编辑、删除）
• 添加一个可根据 Obsidian 模板生成笔记的工具
• 实现按元数据（frontmatter）筛选的搜索
• 实现对新笔记和编辑内容的实时跟踪与更新

配置

在 Obsidian 中打开插件设置进行配置：

1. 服务设置： 端口号，以及服务是否随 Obsidian 自动启动。
2. 嵌入模型： 提供所选 OpenAI 兼容嵌入服务提供商的 URL、模型名称和 API 密钥。使用提供的按钮验证连接。
3. 向量存储：
   • 定义文件模式（类似 .gitignore），以排除特定文件或文件夹，使其不参与索引。您可以直接从知识库的 .gitignore 文件中复制模式。
   • 如有需要，可调整分块参数（大小、重叠长度、分隔符），但默认值通常已足够。
4. MCP 工具： 通过设置中的开关，启用或禁用服务提供的单个工具（如 read_file、create_folder 等）。需要在设置中使用按钮重启服务，所做更改才会生效。

使用方法

1. 配置： 在 Obsidian 设置面板中配置插件，尤其是嵌入模型的详细信息。
2. 索引 Vault： 在 Obsidian 命令面板中运行“Re-index Vault (MCP Server)”命令。simple_vector_search 工具需要完成此步骤才能运行。等待索引过程完成（届时会显示通知）。
3. 启动服务： 确保 MCP 服务正在运行。可以在设置中启用“Auto Start MCP”，或使用“Start MCP Server”命令。
4. 连接外部工具： 将 MCP 客户端（例如，配置为使用 MCP 的 AI 助手）连接到设置中显示的服务端点（例如，http://localhost:8080/sse）。
5. 使用工具： 使用已连接客户端提供的 MCP 工具（simple_vector_search、list_files、read_file 等）与 Obsidian Vault 交互。
6. 在你喜欢的支持 MCP 的客户端中，将 MCP 配置为 SSE 模式，并将端点设为 http://localhost:8080/sse（或你配置的端口）。之后即可使用此插件提供的工具。
7. 停止服务： 不再使用时，运行“Stop MCP Server”命令停止服务。

开发

此项目使用 TypeScript。请确保已安装 Node.js 和 npm。

1. 克隆仓库。
2. 运行 npm install 安装依赖项。
3. 运行 npm run dev 编译插件并监视文件变更。
4. 将 main.js、manifest.json 和 styles.css 文件复制到 Obsidian Vault 的 .obsidian/plugins/mcp-server/ 目录中。
5. 重新加载 Obsidian 并启用插件。

状态与限制

此项目仍在开发中。当前已可使用，并且每天都在使用，但仍可能存在一些问题。

请将其安全性视为尚未经过审查。该服务会通过本地端口开放对 Vault 的读写权限，因此只能在可信任的计算机上运行，并确保端口仅绑定到 localhost。索引会将笔记内容发送到你配置的嵌入端点；除非你将其指向本地模型，否则该端点由第三方提供。

欢迎提交问题和拉取请求，我会尽快回复。

已知问题

1. 文件大小限制： 如果 Vault 中的笔记很多，当 orama.json 文件超过 512MB 时，索引可能会失败。目前除减少笔记或分块数量外，没有其他解决方法。

2. 数字存储： OramaDB 会将浮点数存储为原始字符串，这可能导致数据库大小迅速增加。