使用说明

Obsidian MCP 服务器

一个用Go语言编写的模型上下文协议（MCP）服务器，它通过本地REST API插件与Obsidian集成。该服务器使用官方的MCP Go SDK，并遵循MCP协议规范，通过标准输入/输出（stdio）进行通信。

人工智能开发的这个项目是在GitHub Copilot和Claude Sonnet 4.5（通过VS Code中的GitHub Copilot Chat）的辅助下开发的。

特点/功能

笔记管理创建、读取、更新和删除笔记
搜索在你的保险库中搜索特定文本
保险库信息查看您的保险库及其内容的概览
**官方MCP软件开发工具包（SDK）**使用官方工具构建 MCP Go SDK（MCP Go软件开发工具包）
**Stdio Transport（可译为“标准I/O传输”或根据具体上下文调整为更贴切的表述）**基于进程的通过stdin/stdout进行的通信
与MCP兼容完全兼容2024年11月5日的模型上下文协议
路径规范化自动 .md 所有操作的扩展处理
VS Code 集成与VS Code的MCP扩展无缝工作

先决条件

黑曜石 与……一起 本地REST API 插件已安装并启用
Go 1.21 或之后
已为本地REST API配置API令牌

安装

克隆或下载此项目
安装依赖项：
```
go mod tidy
```
构建服务器：
```
go build -o obsidian-mcp-server
```

配置

当服务器由MCP客户端（如VS Code或Claude Desktop）启动时，通过环境变量进行配置。

所需的环境变量

OBSIDIAN_API_TOKEN您的Obsidian本地REST API令牌
OBSIDIAN_API_BASE_URLObsidian API的基础URL（默认： http://localhost:27123）

获取您的API令牌

打开Obsidian
进入设置 → 社区插件
查找“本地REST API”插件
从插件设置中复制API密钥

使用方法

MCP服务器设计为由MCP客户端（如VS Code或Claude Desktop）启动，并通过标准输入/输出进行通信。通常情况下，您不需要手动运行它。

VS Code 集成

安装MCP扩展 在VS Code中
配置服务器 在 .vscode/mcp.json：

{
  "servers": {
    "obsidian": {
      "command": "/absolute/path/to/obsidian-mcp-server",
      "env": {
        "OBSIDIAN_API_TOKEN": "your-api-token-here",
        "OBSIDIAN_API_BASE_URL": "http://localhost:27123"
      }
    }
  }
}

重新加载 VS Code - MCP扩展将自动启动服务器
使用工具 通过GitHub Copilot Chat或MCP命令

Claude 桌面集成

构建服务器 （如尚未完成）：

go build -o obsidian-mcp-server

配置Claude桌面版 通过编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "/absolute/path/to/obsidian-mcp-server",
      "env": {
        "OBSIDIAN_API_TOKEN": "your-api-token-here",
        "OBSIDIAN_API_BASE_URL": "http://localhost:27123"
      }
    }
  }
}

重启Claude桌面版 - 服务器将在需要时自动启动

手动测试（高级）

对于开发/测试，您可以手动运行服务器并通过标准输入/输出进行交互：

# Set environment variables
export OBSIDIAN_API_TOKEN="your-token"
export OBSIDIAN_API_BASE_URL="http://localhost:27123"

# Run the server
./obsidian-mcp-server

然后通过标准输入发送 JSON-RPC 消息（见下文 MCP 协议示例）。

可用工具

获取笔记 - 获取笔记的内容
- 参数： path （笔记的路径， .md （可选扩展）
创建笔记 - 创建一个新笔记
- 参数： path （路径， .md （可选扩展）， content （笔记内容）
更新说明 - 更新现有笔记
- 参数： path （路径， .md （可选扩展）， content （新内容）
删除笔记 - 删除一条笔记
- 参数： path （笔记的路径， .md （扩展为可选）
列表笔记 - 列出保险库中的所有笔记
- 参数： folder （可选，按文件夹路径过滤）
搜索笔记 - 搜索包含特定文本的笔记
- 参数： query （搜索查询字符串）
获取保险库信息 - 获取保险库的统计数据和信息
- 无参数

注：所有工具都会自动通过添加路径来规范化路径 .md 如果未提供，则使用扩展。你可以使用 "testfile" 或者 "testfile.md" - 两者的工作原理相同。

MCP协议示例

这些示例展示了通过标准输入/输出进行手动测试时的JSON-RPC消息。

初始化

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2024-11-05",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

列出工具

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/list"
}

创建一个笔记

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "create_note",
    "arguments": {
      "path": "My New Note.md",
      "content": "# My New Note\n\nThis is the content of my note."
    }
  }
}

发展

项目结构

obsidian-mcp/
├── main.go              # MCP server with stdio transport and tool handlers
├── api/
│   └── obsidian.go     # Obsidian REST API client
├── security/
│   └── security.go     # Path validation and content sanitization
├── go.mod               # Go module dependencies (includes MCP SDK)
├── go.sum               # Go module checksums
├── .vscode/
│   └── mcp.json         # MCP server configuration for VS Code
├── .gitignore           # Git ignore file
└── README.md            # This file

建筑学

服务器遵循整洁架构原则：

main.go使用官方SDK设置MCP服务器
- 工具注册与输入/输出模式
- 用于标准输入/标准输出通信的StdioTransport
- 基于上下文的API客户端注入
**api/obsidian.go（可翻译为）：用于Obsidian的API接口（或“Obsidian的API实现文件”）**Obsidian REST API 集成
- 本地REST API的HTTP客户端
- 路径规范化（自动 .md 扩展
- 笔记的CRUD操作
**安全性/安全.go（或可译为：安全/安全性文件）**安全工具
- 路径验证（防止目录遍历）
- 内容净化

为生产构建（或：为生产环境准备）

go build -o obsidian-mcp-server .

生成的二进制文件是自包含的，可以部署在任何地方。只需确保在MCP客户端启动时设置了环境变量即可。

故障排除

常见问题

“连接被拒绝”或“拨号 tcp [::1]:27123: 连接：连接被拒绝”:
- 检查Obsidian是否正在运行
- 验证本地REST API插件是否已在Obsidian中启用
- 确认端口（默认27123）与您的本地REST API设置相匹配
“unauthorized”翻译成中文是“未经授权的”:
- 验证您的 OBSIDIAN_API_TOKEN 在Obsidian本地REST API设置中匹配令牌
- 检查您的MCP客户端配置中环境变量是否已正确设置
在VS Code中服务器无法启动：
- 检查MCP扩展输出面板上的错误
- 验证 command 路径在 .vscode/mcp.json 是绝对且正确的
- 确保已构建二进制文件（go build -o obsidian-mcp-server）
- 配置更改后重新加载 VS Code
重复文件（例如，“testfile”和“testfile.md”）:
- 这个问题已在最新版本中修复
- 所有操作现在都一致地对路径进行规范化处理
- 重建服务器： go build -o obsidian-mcp-server
- 重启您的MCP客户端
路径问题：
- 使用正斜杠 / 即使在Windows上
- 路径相对于保险库根目录
- .md 扩展是可选的 - 它会自动添加

调试

检查MCP客户端的输出面板/日志：

VS Code打开输出面板 → 从下拉菜单中选择“MCP: Obsidian”
**Claude Desktop（可译为“Claude桌面版”）**在开发者工具中检查控制台日志

服务器将所有活动记录到标准错误输出（stderr），MCP 客户端会捕获这些信息。

做出贡献

欢迎贡献！请随时提出问题或提交拉取请求。

发展

这个项目是与以下方面共同开发的：

GitHub Copilot - 人工智能辅助的代码生成和编辑
克劳德·莎士比亚十四行诗4.5（注：此处“Claude Sonnet 4.5”可能是一个特定作品或版本的名称，由于“Claude”并非莎士比亚十四行诗的常规关联人物，且直接翻译可能产生歧义，因此这里保留了“Claude”作为专有名词，并将其与“莎士比亚十四行诗4.5”结合，以表达可能指某一特定作品或版本的意思。若“Claude”在此处有特殊含义或背景，请根据实际情况调整翻译。） - 架构设计、问题解决和文档编写（通过GitHub Copilot Chat）

技术栈

Go 1.21+ - 现代、高效的语言，具有强大的并发支持
MCP Go SDK（MCP Go软件开发工具包） - 模型上下文协议的官方SDK
Obsidian 本地 REST API - 与Obsidian资料库集成
StdioTransport（可译为“标准I/O传输”或根据具体上下文简化为“标准传输”，但通常保留原样以指明其技术特性） - 标准MCP通信模式

关键设计决策

**通过HTTP的Stdio（标准输入输出）**遵循MCP最佳实践，服务器使用stdin/stdout进行通信，而不是通过HTTP
官方SDK使用官方的MCP Go SDK可确保协议合规性并降低维护成本
路径规范化自动 .md 扩展处理以提升用户体验（UX）
基于上下文的注入通过上下文传递的API客户端，以实现清晰的处理程序签名

该项目遵循Go的最佳实践，采用了包分离的方式：

main - MCP服务器设置和工具处理程序
api/ - Obsidian REST API 客户端
security/ - 验证和清理实用工具

许可证

麻省理工学院许可证

使用说明

Obsidian MCP 服务器

特点/功能

先决条件

安装

配置

所需的环境变量

获取您的API令牌

使用方法

VS Code 集成

Claude 桌面集成

手动测试（高级）

可用工具

MCP协议示例

初始化

列出工具

创建一个笔记

发展

项目结构

建筑学

为生产构建（或：为生产环境准备）

故障排除

常见问题

调试

做出贡献

发展

技术栈

关键设计决策

许可证

相关 MCP

Qdrant向量搜索MCP服务器

Flomo笔记服务

Obsidian MCP 服务器

Obsidian笔记搜索服务

Apple Notes自动化服务

模型上下文协议服务器