内容
# Obsidian 只读 MCP
用于查询正在运行的 Obsidian 知识库的只读 MCP 工具。
## 为什么存在
Obsidian 命令行工具不仅是一个文件系统读取器；它还与你的主 Obsidian 应用程序连接。诸如 `backlinks`、`links`、`outline` 和索引 `search` 之类的命令需要与正在运行的 Obsidian 应用程序进行通信。在智能运行时，代理的文件系统沙盒可能会阻止或破坏该应用程序/IPC 边界。例如，在代理沙盒中运行 `obsidian help` 可能会导致 Obsidian 应用程序崩溃。
给予整个代理无限制的 shell 访问权限可以解决 IPC 问题，但这也给了代理太多权限。这个 MCP 服务器是一个更窄的解决方案：
```text
沙盒代理
-> 只读 MCP 工具调用
-> 主机端 MCP 服务器
-> Obsidian 命令行工具
-> 运行中的 Obsidian 应用程序
```
代理可以保持在沙盒中。主机端的 MCP 服务器获得与 Obsidian 通信的权限，但它只公开了一个固定的只读 Obsidian 命令的允许列表。
## 安全模型
该服务器：
- 只公开只读 Obsidian 操作
- 拒绝未知工具
- 验证知识库相对路径并拒绝 `..` 路径遍历
- 直接构建 `obsidian` argv 而不进行 shell 插值
- 限制输出大小
- 超时长调用
它 **不** 公开：
- 笔记创建或编辑
- 删除、移动、重命名、追加、prepend
- 属性突变
- 插件/主题安装、启用、禁用、重载、卸载
- `obsidian command`
- `obsidian eval`
- 应用程序重载/重启/打开/标签/工作区突变
- 浏览器/网页/打开操作
如果您需要这些功能，请随意修改它以添加这些功能。
## 工具
核心知识库读取：
- `search`
- `search_context`
- `read`
- `daily_read`
- `daily_path`
- `backlinks`
- `links`
- `outline`
- `aliases`
- `tags`
- `tag`
- `unresolved`
- `properties`
- `property_read`
- `help`
通过 Obsidian 读取文件系统/索引：
- `file`
- `files`
- `folder`
- `folders`
- `wordcount`
- `deadends`
- `orphans`
- `recents`
- `random_read`
- `vault`
- `vaults`
- `version`
结构化功能：
- `bases`
- `base_query`
- `base_views`
- `bookmarks`
- `tasks`
- `templates`
- `template_read`
- `snippets`
- `snippets_enabled`
历史/配置元数据读取：
- `diff`
- `history`
- `history_list`
- `history_read`
- `hotkey`
- `hotkeys`
- `plugins`
- `plugin`
- `plugins_enabled`
- `theme`
- `themes`
- `tabs`
- `workspace`
- `workspaces`
- `commands`
开发人员只读检查：
- `dev_console`
- `dev_errors`
- `dev_css`
- `dev_dom`
## 使用 `uvx` 安装
你可以直接从 GitHub 运行 MCP 服务器，而无需克隆仓库：
```toml
[mcp_servers.obsidian_readonly]
command = "uvx"
args = [
"--from",
"git+https://github.com/eothL/obsidian-readonly-mcp",
"obsidian-readonly-mcp"
]
[mcp_servers.obsidian_readonly.env]
OBSIDIAN_READONLY_VAULT = "你的知识库名称"
```
使用 Obsidian 知识库名称，而不是文件系统路径。它应该与你传递给 `obsidian vault="你的知识库名称"` 的值相同。
如果该包稍后发布到 PyPI，配置可以变为：
```toml
[mcp_servers.obsidian_readonly]
command = "uvx"
args = ["obsidian-readonly-mcp"]
[mcp_servers.obsidian_readonly.env]
OBSIDIAN_READONLY_VAULT = "你的知识库名称"
```
重启 Codex 或启动新线程，以便发现 MCP 服务器。
## 从本地克隆安装
将此仓库克隆到某个稳定位置，然后将 MCP 服务器添加到你的 Codex 配置中：
```toml
[mcp_servers.obsidian_readonly]
command = "python3"
args = ["/absolute/path/to/obsidian-readonly-mcp/src/obsidian_readonly_mcp.py"]
[mcp_servers.obsidian_readonly.env]
OBSIDIAN_READONLY_VAULT = "你的知识库名称"
```
重启 Codex 或启动新线程，以便发现 MCP 服务器。
## Codex 插件
此仓库还包含 Codex 插件元数据：
- `.codex-plugin/plugin.json`
- `.mcp.json`
- `skills/obsidian-readonly-mcp/SKILL.md`
该插件捆绑了 MCP 服务器和配套技能，以便 Codex 可以学习在知识库探索时优先使用只读 Obsidian 工具。该插件的 MCP 配置不硬编码知识库名称；在环境中设置 `OBSIDIAN_READONLY_VAULT` 或在工具调用中传递 `vault` 参数。
## 用法
加载后，工具以以下名称公开：
```text
mcp__obsidian_readonly__search
mcp__obsidian_readonly__read
mcp__obsidian_readonly__backlinks
mcp__obsidian_readonly__links
mcp__obsidian_readonly__outline
```
示例工具参数：
```json
{"query": "代理 内存"， "limit": 10}
```
```json
{"file": "代理 内存"， "counts": true, "format": "json"}
```
## 本地烟雾测试
打开 Obsidian：
```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}' \
| python3 src/obsidian_readonly_mcp.py
```
端到端读取：
```bash
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"代理 内存","limit":3}}}' \
| python3 src/obsidian_readonly_mcp.py
```
## 配套技能
此仓库在 `skills/obsidian-readonly-mcp/` 中包含一个 Codex 技能。如果您希望代理自动优先使用这些工具进行 Obsidian 知识库探索，请安装或复制该技能到您的 Codex 技能目录中。
