Obsidian Go MCP

OBX

   

快速、轻便 主控程序 服务器 黑曜石 拱顶。内置Go，速度和简单。

为什么是这个项目？

快速开始

1.使用一个命令安装：

curl -sSL https://raw.githubusercontent.com/zach-snell/obx/main/install.sh | bash

此自动检测您的操作系统/架构并安装到 /usr/local/bin.

没有sudo？ 安装到 ~/.local/bin 相反： ``bash curl -sSL https://raw.githubusercontent.com/zach-snell/obx/main/install.sh | bash -s -- --user ``

Manual download

# macOS (Apple Silicon)
curl -sSL https://github.com/zach-snell/obx/releases/latest/download/obx-darwin-arm64 -o obx && chmod +x obx

# macOS (Intel)
curl -sSL https://github.com/zach-snell/obx/releases/latest/download/obx-darwin-amd64 -o obx && chmod +x obx

# Linux
curl -sSL https://github.com/zach-snell/obx/releases/latest/download/obx-linux-amd64 -o obx && chmod +x obx

2.配置您的MCP客户端：

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/obx",
      "args": ["mcp", "/path/to/your/vault"]
    }
  }
}

Claude Code

服务器将被自动发现，或添加到您的配置中：

{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/obx",
      "args": ["mcp", "/path/to/your/vault"]
    }
  }
}

HTTP Streamable Transport

作为HTTP服务器运行，用于远程访问或多客户端设置：

# Start HTTP server on port 8080
obx mcp /path/to/vault --http :8080
# or via env var
OBSIDIAN_ADDR=:8080 obx mcp /path/to/vault

然后配置您的MCP客户端以连接到 http://localhost:8080/mcp.

Other MCP Clients

# Run directly (communicates via stdio, default)
obx mcp /path/to/vault

3.开始使用它！ 让你的AI助手搜索你的保险库、创建笔记、管理任务等。

⚠️ 路径是相对于vault根的。 全部 path 参数使用以下路径 projects/todo.md，而不是完整的文件系统路径。使用绝对路径将在vault中创建嵌套目录。

安装选项

预构建二进制文件（推荐）

下载自 发布:

去安装

go install github.com/zach-snell/obx/cmd/obx@latest
mv $(go env GOPATH)/bin/server $(go env GOPATH)/bin/obx

从源代码构建

git clone https://github.com/zach-snell/obx.git
cd obx
go build -o obx ./cmd/obx

升级

只需再次运行安装脚本-它总是获取最新版本：

curl -sSL https://raw.githubusercontent.com/zach-snell/obx/main/install.sh | bash

高级服务器配置

obx mcp 支持用于严格访问控制和动态操作的标志：

选择性工具禁用

如果你不想让人工智能助手访问特定的工具（例如批量操作或删除），你可以使用 --disabled-tools 标志：

obx mcp /my/vault --disabled-tools manage-folders,bulk-operations,manage-frontmatter

动态保险库切换

默认情况下，a obx mcp 实例被锁定到单个vault路径。如果您想允许LLM通过MCP协议动态切换活动保管库，而无需重新启动服务器，请按如下方式启用它：

obx mcp /my/vault --allow-vault-switching

要限制代理可以切换到哪些保管库，请首先使用设置命令定义别名，如 obx vault add my-notes /path/to/notes，然后将允许的别名传递给服务器：

obx mcp /my/vault --allow-vault-switching --allowed-vaults my-notes,work,personal

______________________________________________________________________

MCP工具参考（16倍）

obx 将其72个动作复用到16个MCP工具组中，以防止上下文窗口耗尽，并在LLM工具限制下保持良好状态（例如，光标允许40，副驾驶允许128）。你通过一个 "action" 将参数传递给每个工具，以路由到特定功能。

\[！注意\] 对于详尽的列表 action 每个工具组接受的参数，请阅读 官方文档网站.

______________________________________________________________________

令牌高效+安全写入

高频工具现在支持紧凑响应，破坏性工具支持预览优先工作流。

响应模式

• mode=compact （默认）：带有摘要+有界数据的小JSON信封
• mode=detailed：遗留markdown丰富的输出供人类阅读

紧凑型信封示例：

{
  "status": "ok",
  "mode": "compact",
  "summary": "Found 42 notes",
  "truncated": false,
  "data": {
    "total_count": 42,
    "returned_count": 42
  }
}

破坏性/散装工具的试运行

使用 dry_run=true 无需写入即可预览操作：

• delete-note, delete-folder
• bulk-tag, bulk-move, bulk-set-frontmatter
• merge-notes, extract-note, extract-section
• batch-edit-note

开放式并发

写入/编辑工具接受可选 expected_mtime （RFC3339Nano）。\ 如果文件修改时间不同，操作将失败，而不是覆盖较新的更改。

______________________________________________________________________

使用示例

日常工作流程

"Create today's daily note and show me my open tasks"
"What did I work on last week?"
"Find notes I haven't touched in 3 months"

研究与写作

"Search my vault for anything about 'machine learning'"
"Find all notes tagged #project and #active"
"What notes mention 'API design' but aren't linked?"

保险库维护

"Find orphan notes with no connections"
"Show me stub notes under 100 words"
"Generate a MOC for my projects folder"

批量操作

"Add #archive tag to all notes in the old-projects folder"
"Move all notes tagged #2023 to the archive folder"
"Set status: complete on these 5 project notes"

______________________________________________________________________

模板变量

在您的 templates/ 文件夹：

---
title: {{title}}
date: {{date}}
status: {{status:draft}}
---

# {{title}}

Created: {{datetime}}

内置变量

使用 {{var:default}} 默认值。

______________________________________________________________________

任务格式

兼容 黑曜石任务 插件：

- [ ] Open task
- [x] Completed task
- [ ] Has due date 📅 2024-01-15
- [ ] High priority ⏫
- [ ] Medium priority 🔼
- [ ] Low priority 🔽
- [ ] Tagged #project #urgent

______________________________________________________________________

安全

• 路径遍历保护：所有文件操作都将沙盒到您的保管库中
• 默认情况下为只读：写入操作需要显式的工具调用
• 无网络访问：服务器仅访问本地文件

______________________________________________________________________

发展

# Setup (requires Go 1.21+)
git clone https://github.com/zach-snell/obx.git
cd obx

# With mise (recommended)
mise install && mise run check

# Without mise
go build -o obx ./cmd/obx
go test -race -cover ./...
go test -bench 'Benchmark(ListNotes|SearchVault)' ./internal/vault

可用命令

______________________________________________________________________

常见问题解答

Q： 我需要黑曜石跑步吗？\ A： 不是。此服务器直接处理磁盘上的vault文件。

Q： 这会与黑曜石产生冲突吗？\ A： 不可以。两者都可以安全地访问相同的文件。

Q： 同步（iCloud、Dropbox等）怎么样？\ A： 工作得很好。服务器读取/写入标准markdown文件。

Q： 我可以使用多个保险库吗？\ A： 是的！您有两个主要选择：

1. 运行多个服务器实例，每个实例指向不同端口上的不同保管库。
2. 通过以下方式在全球注册保管库 `obx vault add

并使用以下命令运行服务器 obx mcp --allow-vault-switching --allowed-vaults 这暴露了一个 manage-vaults` MCP工具允许AI助手在它们之间动态切换。

______________________________________________________________________

许可证

Apache 2.0-请参阅 许可证