内容
# obsidian-mcp
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，允许任何兼容MCP的AI主机（Cursor、Claude Desktop、Zed等）读取、搜索、链接和写入本地Markdown / [Obsidian](https://obsidian.md)保险库中的笔记。
[](https://github.com/darrenlopez/obsidian-mcp/actions/workflows/ci.yml)
[](https://www.python.org/downloads/)
[](./LICENSE)
---
## 这是什么？
`obsidian-mcp` 是一个 [MCP](https://modelcontextprotocol.io) 服务器。MCP是Anthropic开放的标准，用于连接AI助手与外部工具和数据源——可以理解为“AI应用的USB-C接口”。一旦该服务器注册到MCP主机上，您就可以向模型提问：
> *"我这周关于MCP学到了什么，哪些笔记链接到了它？*"
…and 模型将调用此服务器的工具（`search_notes`、`find_backlinks`、`get_recent_notes`等）来回答问题，使用的是**您**的实际笔记。
## 状态
| 阶段 | 范围 | 状态 |
|------:|------|------|
| 0 | 仓库骨架、CI、示例保险库、带有`get_note`的服务器存根 | **已完成** |
| 1 | 沙盒路径、解析器、读取器、测试 | **已完成** |
| 2 | 搜索、列表、反向链接、标签索引 | 计划中 |
| 3 | 资源（笔记作为`obsidian://` URI） | 计划中 |
| 4 | 写入工具（`create_note`、`append_to_note`）+ 原子写入 | 计划中 |
| 5 | 提示（`/weekly-review`、`/daily-note-template`） | 计划中 |
## 架构
```text
┌────────────────┐ stdio JSON-RPC ┌────────────────────────┐
│ MCP主机 │ ───────────────────► │ obsidian-mcp 服务器 │
│ （Cursor / │ │ （此仓库） │
│ Claude / │ │ │
│ Zed） │ │ 工具 / 资源 / │
└────────────────┘ │ 提示 │
└───────────┬────────────┘
│
沙盒化 ▼
┌────────────────────────┐
│ 本地Markdown保险库 │
└────────────────────────┘
```
所有调用者提供的路径都会通过单个沙盒函数（`utils/pathing.py::safe_resolve`）过滤，然后才能访问文件系统，因此服务器不能被强制读取配置的保险库根目录以外的文件。
## 快速入门
### 1. 安装
```bash
git clone https://github.com/darrenlopez/obsidian-mcp.git
cd obsidian-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
```
### 2. 在捆绑的示例保险库中试用
```bash
OBSIDIAN_MCP_VAULT_PATH="$(pwd)/sample-vault" \
npx @modelcontextprotocol/inspector \
python -m obsidian_mcp
```
这将启动Anthropic官方的 [MCP Inspector](https://github.com/modelcontextprotocol/inspector)，指向此服务器，因此您可以交互式地调用`get_note`并在浏览器中检查模式，而无需离开浏览器。
### 3. 在Cursor中注册
将以下内容添加到您的Cursor MCP配置中
（`~/.cursor/mcp.json` 或 Cursor设置UI）：
```json
{
"mcpServers": {
"obsidian": {
"command": "python",
"args": ["-m", "obsidian_mcp"],
"env": {
"OBSIDIAN_MCP_VAULT_PATH": "/absolute/path/to/your/vault",
"OBSIDIAN_MCP_READ_ONLY": "false"
}
}
}
}
```
### 4. 在Claude Desktop上注册
将相同的块添加到 `~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS上（或平台等效）。
## 配置
所有配置均通过环境变量（前缀`OBSIDIAN_MCP_`）进行。
| 变量 | 默认值 | 目的 |
|---|---|---|
| `OBSIDIAN_MCP_VAULT_PATH` | *(必填)* | 保险库根目录的绝对路径。 |
| `OBSIDIAN_MCP_READ_ONLY` | `false` | 当`true`时，不注册写入工具。 |
| `OBSIDIAN_MCP_MAX_FILE_KB` | `1024` | 读取操作返回的最大笔记大小（KiB）。 |
| `OBSIDIAN_MCP_INCLUDE_HIDDEN` | `false` | 在列表/搜索中包含点文件和`.obsidian/`。 |
## 工具（阶段0 / 1）
| 工具 | 描述 |
|------|-------------|
| `get_note(path)` | 读取单个笔记，返回解析的前面信息、标签和输出的维基链接。 |
第2+阶段的工具表面（`search_notes`、`list_notes`、`find_backlinks`、`list_tags`、`get_recent_notes`等）已在
[架构计划](#architecture) 中记录，并跟踪在 [`STATUS`](#status) 中。
## 安全
此服务器读取（在非只读模式下写入）您机器上的文件。一些选择限制了爆炸半径：
- **沙盒路径。** 每个路径都通过`safes_resolve(vault_root, user_input)`解析，该函数拒绝绝对路径、`..`段和符号链接逃逸，然后再进行文件系统操作。
- **只读模式。** 设置`OBSIDIAN_MCP_READ_ONLY=true`，不注册写入工具。
- **大小限制。** `OBSIDIAN_MCP_MAX_FILE_KB`限制了读取操作返回的字节，以防止通过大文件进行DoS攻击。
- **隐藏文件排除。** 默认情况下跳过`.obsidian/`和点文件，因此插件机密不会泄漏到模型上下文中。
- **无网络。** 服务器本身不进行任何出站网络请求。
- **无`shell=True`，无`eval`.** 任何地方。
## 开发
```bash
pip install -e ".[dev]"
ruff check .
ruff format --check .
mypy
pytest
```
测试套件包括对抗性路径遍历测试
（`tests/test_pathing.py`）- 保持它们绿色。
## 许可证
[MIT](./LICENSE)
