Obsidian Local Rest Api Mcp

笔记 TypeScript

🚀 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）能够更有效地进行推理。

前后对比：变革之处

旧方法（基于CRUD）	新方法（AI原生）	优势
`list_files`（返回所有内容）	`list_directory(path, limit, offset)`	通过分页防止上下文溢出
`create_file` + `update_file`	`write_file(path, content, mode)`	单个工具处理创建、更新和追加操作
`create_note` + `update_note`	`create_or_update_note(path, content, frontmatter)`	智能的插入或更新操作，消除决策复杂性
`search_notes(query)`	`search_vault(query, scope, path_filter)`	精确、可指定范围的搜索，支持高级过滤
(无等效操作)	`get_daily_note(date)`	针对常见工作流程的高级抽象
(无等效操作)	`get_recent_notes(limit)`	面向任务的最近文件访问
(无等效操作)	`find_related_notes(path, on)`	概念关系发现

📦 可用工具

目录和文件操作

`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客户端显示“启动失败”或类似错误：

直接测试服务器：
```
npx obsidian-local-rest-api-mcp --version
```
应输出版本号。

测试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);
"

应显示初始化响应。

检查环境变量：
- 确保 OBSIDIAN_API_URL 指向正在运行的Obsidian Local REST API
- 直接测试API：curl http://obsidian-local-rest-api.test/api/files（或您配置的API URL）
验证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密钥

🤝 贡献

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

📄 许可证

本项目采用MIT许可证。

0 条评论
分类：笔记

Obsidian Local Rest Api Mcp