Obsidian Local Rest Api MCP

🚀 Obsidian Local REST API MCP Server

这是一个基于AI原生的MCP（模型上下文协议）服务器，它通过本地REST API提供智能、面向任务的工具，用于与Obsidian保险库进行交互。

🚀 快速开始

前提条件

• Node.js 18+ 或 Bun 运行时
• Obsidian Local REST API 在本地运行（默认地址：http://obsidian-local-rest-api.test）

安装

使用 npx（推荐）

npx obsidian-local-rest-api-mcp

从源代码安装

# 克隆仓库
git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git
cd obsidian-local-rest-api-mcp

# 使用 bun 安装依赖
bun install

# 构建项目
bun run build

配置

设置API连接的环境变量：

export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test"  # 默认URL（对于非Valet设置，可使用 http://localhost:8000）
export OBSIDIAN_API_KEY="your-api-key"          # 可选的Bearer令牌

运行服务器

# 开发模式，支持自动重新加载
bun run dev

# 生产模式
bun run start

# 或者直接运行
node build/index.js

MCP客户端配置

Claude Desktop

在 claude_desktop_config.json 中添加以下内容：

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": ["obsidian-local-rest-api-mcp"],
      "env": {
        "OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test",
        "OBSIDIAN_API_KEY": "your-api-key-if-needed"
      }
    }
  }
}

带有MCP扩展的VS Code

使用包含的 .vscode/mcp.json 配置文件。

✨ 主要特性

🧠 AI原生设计理念

此MCP服务器按照AI原生原则进行了重新设计，而非简单的API到工具映射。它不暴露低级的CRUD操作，而是提供高级的、面向任务的工具，使大语言模型（LLM）能够更有效地进行推理。

前后对比：变革之处

📦 可用工具

目录和文件操作

list_directory

用途：通过分页列出目录内容，防止上下文溢出

{
  "path": "Projects/",
  "recursive": false,
  "limit": 20,
  "offset": 0
}

对AI的好处：LLM可以逐步探索保险库结构，而不会使上下文过载

read_file

用途：读取保险库中任何文件的内容

{"path": "notes/meeting-notes.md"}

write_file

用途：以多种模式写入文件，取代了单独的创建和更新操作

{
  "path": "notes/summary.md",
  "content": "# Meeting Summary\n...",
  "mode": "append"  // "overwrite", "append", "prepend"
}

对AI的好处：单个工具处理所有写入场景，消除歧义

delete_item

用途：删除任何文件或目录

{"path": "old-notes/"}

AI原生笔记操作

create_or_update_note

用途：智能的插入或更新操作，如果笔记不存在则创建，如果存在则更新

{
  "path": "daily/2024-12-26",
  "content": "## Tasks\n- Review AI-native MCP design",
  "frontmatter": {"tags": ["daily", "tasks"]}
}

对AI的好处：消除了“这个笔记是否存在？”的决策树

get_daily_note

用途：使用常见的命名模式智能检索每日笔记

{"date": "today"}  // 或者 "yesterday", "2024-12-26"

对AI的好处：抽象了文件系统细节和命名约定

get_recent_notes

用途：获取最近修改的笔记

{"limit": 5}

对AI的好处：匹配自然的“我最近处理了哪些内容？”查询

高级搜索和发现

search_vault

用途：支持多范围搜索和高级过滤

{
  "query": "machine learning",
  "scope": ["content", "filename", "tags"],
  "path_filter": "research/"
}

对AI的好处：精确、有针对性的搜索减少了噪声

find_related_notes

用途：发现笔记之间的概念关系

{
  "path": "ai-research.md",
  "on": ["tags", "links"]
}

对AI的好处：支持基于关系的工作流程和意外发现

遗留工具（向后兼容）

服务器保持与现有工具（如 get_note、list_notes、get_metadata_keys 等）的向后兼容性。

🔧 技术细节

架构

• ObsidianApiClient - REST API端点的HTTP客户端包装器
• ObsidianMcpServer - 带有工具处理程序的MCP服务器实现
• Configuration - 基于环境的配置，带有验证功能

错误处理

服务器包含全面的错误处理机制：

• API连接失败
• 无效的工具参数
• 网络超时
• 身份验证错误

错误以MCP工具调用响应的形式返回，并带有描述性消息。

调试

通过设置环境变量启用调试日志：

export DEBUG=1
export NODE_ENV=development

服务器日志写入标准错误输出（stderr），以避免干扰标准输出（stdout）上的MCP协议通信。

📚 故障排除

MCP服务器启动失败

如果MCP客户端显示“启动失败”或类似错误：

1. 直接测试服务器：

   npx obsidian-local-rest-api-mcp --version
   

   应输出版本号。
2. 测试MCP协议：

   # 运行测试脚本
   node -e "
   const { spawn } = require('child_process');
   const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] });
   child.stdout.on('data', d => console.log('OUT:', d.toString()));
   child.stderr.on('data', d => console.log('ERR:', d.toString()));
   setTimeout(() => {
     child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'\n');
     setTimeout(() => child.kill(), 2000);
   }, 500);
   "
   

   应显示初始化响应。
3. 检查环境变量：
   • 确保 OBSIDIAN_API_URL 指向正在运行的Obsidian Local REST API
   • 直接测试API：curl http://obsidian-local-rest-api.test/api/files（或您配置的API URL）
4. 验证Obsidian Local REST API：
   • 安装并运行 Obsidian Local REST API
   • 确认它在配置的端口上可访问
   • 检查是否需要身份验证

常见问题

• “Command not found”：确保已安装Node.js/npm，并且npx可用
• “Connection refused”：Obsidian Local REST API未运行或URL错误
• Laravel Valet .test域名：如果使用Laravel Valet，确保项目目录名称与.test域名匹配（例如，obsidian-local-rest-api.test 对应 /obsidian-local-rest-api/ 项目目录）
• “Unauthorized”：检查是否需要API密钥，并确保配置正确
• “Timeout”：在客户端配置中增加超时时间，或检查网络连接

Cherry Studio配置

对于Cherry Studio，请使用以下确切设置：

• 名称：obsidian-vault（或您喜欢的任何名称）
• 类型：Standard Input/Output (stdio)
• 命令：npx
• 参数：obsidian-local-rest-api-mcp
• 环境变量：
  • OBSIDIAN_API_URL：您的API URL（例如，对于Laravel Valet，使用 http://obsidian-local-rest-api.test）
  • OBSIDIAN_API_KEY：如果需要身份验证，提供可选的API密钥

🤝 贡献

1. 分叉仓库
2. 创建功能分支
3. 使用适当的TypeScript类型进行更改
4. 使用您的Obsidian保险库进行测试
5. 提交拉取请求

📄 许可证

本项目采用MIT许可证。