内容
# MCP 服务器适用于 Obsidian （Go语言版）
适用于Obsidian的MCP服务器的Go语言实现，通过[本地REST API](https://github.com/coddingtonbear/obsidian-local-rest-api)社区插件与Obsidian交互。
这是由[Markus Pfundstein](https://github.com/MarkusPfundstein)开发的原始[Python实现](https://github.com/MarkusPfundstein/mcp-obsidian)的移植版本，使用官方的[modelcontextprotocol/go-sdk](https://github.com/modelcontextprotocol/go-sdk)构建。
> **直接替换：** 所有13种工具都暴露相同的名称和参数与Python版本相同。现有的Claude Desktop配置只需要将`command`路径更新为指向Go二进制文件 — 无需其他更改。
## 为什么选择Go语言移植版本？
- **易于分发** — 编译一次，交付一个单独的、自包含的二进制文件，无需运行时依赖。无需Python，无需`uv`，无需虚拟环境。
- **优化执行** — 相比Python进程，内存占用更低，启动速度更快。
- **跨平台** — `go build`从同一源代码为macOS、Linux和Windows生成原生二进制文件。
## 工具列表
| 工具 | 描述 |
|------|-------------|
| `obsidian_list_files_in_vault` | 列出保险库根目录下的所有文件和目录 |
| `obsidian_list_files_in_dir` | 列出指定保险库目录下的所有文件和目录 |
| `obsidian_get_file_contents` | 返回单个文件的内容 |
| `obsidian_batch_get_file_contents` | 返回多个文件的内容，连接后 |
| `obsidian_append_content` | 将Markdown内容追加到新或现有文件中 |
| `obsidian_put_content` | 创建或替换具有给定内容的文件 |
| `obsidian_patch_content` | 在标题、块引用或前置字段处插入内容 |
| `obsidian_delete_file` | 从保险库中删除文件或目录 |
| `obsidian_simple_search` | 跨所有保险库文件进行全文搜索 |
| `obsidian_complex_search` | JsonLogic查询搜索（支持`glob`和`regexp`运算符） |
| `obsidian_get_periodic_note` | 获取当前定期笔记（每日/每周/每月/每季度/每年） |
| `obsidian_get_recent_periodic_notes` | 获取给定周期类型的最近定期笔记 |
| `obsidian_get_recent_changes` | 获取最近修改的保险库文件 |
## 先决条件
- Go 1.23 或更高版本
- [Obsidian 本地 REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) 插件已安装并在 Obsidian 中启用
## 配置
服务器通过环境变量配置。您可以直接设置它们或在工作目录中使用`.env`文件。
| 变量 | 必需 | 默认值 | 描述 |
|----------|----------|---------|-------------|
| `OBSIDIAN_API_KEY` | **是** | — | 来自Obsidian插件设置的API密钥 |
| `OBSIDIAN_HOST` | 否 | `127.0.0.1` | Obsidian运行的主机名 |
| `OBSIDIAN_PORT` | 否 | `27124` | Obsidian REST API插件的端口 |
| `OBSIDIAN_PROTOCOL` | 否 | `https` | 协议（`http`或`https`） |
示例`.env`文件：
```env
OBSIDIAN_API_KEY=您的_API_密钥_在此
OBSIDIAN_HOST=127.0.0.1
OBSIDIAN_PORT=27124
```
您可以在Obsidian → 设置 → 本地REST API找到API密钥。
## 快速入门
### 构建
```sh
cd mcp-obsidian-go
go build -o mcp-obsidian ./cmd/mcp-obsidian
```
在Windows上：
```sh
go build -o mcp-obsidian.exe ./cmd/mcp-obsidian
```
### 运行
```sh
OBSIDIAN_API_KEY=您的密钥_在此 ./mcp-obsidian
```
## MCP 客户端配置
### Claude Desktop
配置文件位置：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
#### 使用预编译二进制文件
```json
{
"mcpServers": {
"mcp-obsidian-go": {
"command": "/path/to/mcp-obsidian",
"env": {
"OBSIDIAN_API_KEY": "<您的_API_密钥_在此>"
}
}
}
}
```
#### 直接从源代码使用 `go run`
```json
{
"mcpServers": {
"mcp-obsidian-go": {
"command": "go",
"args": [
"run",
"/path/to/mcp-obsidian-go/cmd/mcp-obsidian"
],
"env": {
"OBSIDIAN_API_KEY": "<您的_API_密钥_在此>",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}
}
}
```
## 项目结构
```
mcp-obsidian-go/
├── cmd/
│ └── mcp-obsidian/
│ └── main.go # 入口点：连接配置 → 客户端 → MCP服务器
├── internal/
│ ├── config/
│ │ └── config.go # 加载和验证环境变量
│ ├── obsidian/
│ │ └── client.go # Obsidian本地REST API的HTTP客户端
│ └── tools/
│ ├── vault.go # 8个保险库文件工具
│ ├── search.go # 2个搜索工具
│ ├── periodic.go # 3个定期笔记/最近更改工具
│ └── register.go # 将所有工具组注册到MCP服务器
├── go.mod
└── go.sum
```
## 文档
详细文档位于[`docs/`](docs/)文件夹中：
| 文档 | 描述 |
|----------|-------------|
| [docs/architecture.md](docs/architecture.md) | 数据流、包布局和关键设计决策 |
| [docs/tools-reference.md](docs/tools-reference.md) | 所有13种工具的参数完整参考和示例 |
| [docs/configuration.md](docs/configuration.md) | 所有环境变量、`.env`用法和故障排除 |
| [docs/clients.md](docs/clients.md) | Claude Desktop、Cursor、VS Code等客户端的配置代码段 |
| [docs/contributing.md](docs/contributing.md) | 如何添加新工具和贡献指南 |
## 备注
- Obsidian本地REST API在localhost上使用自签名TLS证书；为本地连接故意禁用TLS验证。
- `obsidian_batch_get_file_contents`没有专用的API端点；文件依次获取并在客户端连接。
- `obsidian_get_recent_changes`在底层使用Dataview DQL查询；必须在Obsidian中安装Dataview插件。
## 鸣谢
本项目是[Markus Pfundstein](https://github.com/MarkusPfundstein)的[mcp-obsidian](https://github.com/MarkusPfundstein/mcp-obsidian)的Go语言移植版本。原始想法、工具设计和Python实现的所有功劳归于他。
