# Obsidian MCP

Canonical: https://cqbase.net/zh/entry/mcp-obsidian
Chinese: https://cqbase.net/zh/entry/mcp-obsidian
English: https://cqbase.net/en/entry/mcp-obsidian

> 通过 Obsidian 的 REST API 社区插件，让 MCP 客户端读写你的笔记库。

MarkusPfundstein/mcp-obsidian 是 MIT 许可的 MCP 服务器，经由 Obsidian 的 REST API 社区插件与笔记库交互。代理因此可能读取或改写你的笔记。

笔记库里常有日记和密钥备忘。先用一个隔离的测试库，关掉不需要的写权限。不要把生产库的 API 令牌交给远端代理环境。

推荐来源：

- [@beamnxw](https://x.com/beamnxw/status/2099797510080360913) 在 2026 年 9 月 15 日 的帖子里提到了这个项目（数字采集于 2026 年 11 月 15 日：633 次喜欢，105 次转发）。

## 解决什么问题

Obsidian MCP（仓库 `MarkusPfundstein/mcp-obsidian`）通过 Obsidian 的 Local REST API 社区插件，让 MCP 客户端读写你的笔记库。它并不直接扫描磁盘上的库目录，而是向插件提供的本地 HTTP 接口发请求。因此，Obsidian 必须开着，并且该插件已经启用。

官方 README 列出的工具包括：`list_files_in_vault`、`list_files_in_dir`、`get_file_contents`、`search`、`patch_content`、`append_content` 和 `delete_file`。其中后三项会改笔记，`delete_file` 还能删除目录。

## 适合谁

适合已经在用 Obsidian，并希望 Claude Desktop 或其他 MCP 客户端查询、整理笔记的人。项目使用 MIT 许可。要求 Python 3.11 或更新版本。

笔记库里常有日记和密钥备忘。请先用一个隔离的测试库，关掉不需要的写权限，不要把生产库的 API 令牌交给远端代理环境。

## 怎么装

核验日期为 2026-11-15（Asia/Shanghai）。步骤来自仓库 [README](https://github.com/MarkusPfundstein/mcp-obsidian)。

先在 Obsidian 中安装并启用社区插件 [Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api)，再从插件设置里复制 API 密钥。默认主机是 `127.0.0.1`，默认端口是 `27124`；若你改过插件里的值，配置里也要一起改。

README 写明的客户端配置主要针对 Claude Desktop。macOS 路径是 `~/Library/Application Support/Claude/claude_desktop_config.json`，Windows 路径是 `%APPDATA%/Claude/claude_desktop_config.json`。已发布包装使用 `uvx`：

```json
{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": ["mcp-obsidian"],
      "env": {
        "OBSIDIAN_API_KEY": "<YOUR_OBSIDIAN_API_KEY>",
        "OBSIDIAN_HOST": "<your_obsidian_host>",
        "OBSIDIAN_PORT": "<your_obsidian_port>"
      }
    }
  }
}
```

官方还提到，Claude 有时找不到 `uv` 或 `uvx`。这时可用 `which uvx` 查出绝对路径，把 `command` 改成这条路径。第二种方式是在工作目录放 `.env`，写入 `OBSIDIAN_API_KEY`、`OBSIDIAN_HOST` 和 `OBSIDIAN_PORT`；官方仍把写进服务器配置的方式列为首选。

仓库也提供 Docker 配置。因为 MCP 走 stdio，客户端必须用 `docker compose run --rm -T`，不能用 `docker compose up`。从容器访问本机插件时，示例把 `OBSIDIAN_HOST` 设为 `host.docker.internal`。

README 没有给出 Cursor 或 Claude Code 的现成命令。其他接受标准 `mcpServers` 条目的客户端，可以沿用上面的 `uvx` 和环境变量，但本文不编造未经官方写出的启动命令。

## 一个实际例子

下面的提示词改写自 README 的示例，用作核验，不是官方固定口令。本次没有连接真实笔记库，因此不编造搜索结果。

1. 打开一个不含私人日记或密钥的测试库，启用 Local REST API，把密钥只写进本地 MCP 配置。
2. 确认 Obsidian 保持运行，客户端能看到 `search` 和 `get_file_contents`。
3. 先明确告诉代理使用 Obsidian，再发送：`Search the vault for notes that mention "weekly review". Summarize the matching notes. Do not append, patch, or delete anything.`
4. 自己打开那些笔记，核对摘要是否属实。若代理要写入或删除，先拒绝，直到你改用测试库并明确允许。

## 常见坑

- Obsidian 没开，或插件没启用，连接被拒绝。[issue #76](https://github.com/MarkusPfundstein/mcp-obsidian/issues/76)（2026-11-15 仍为 open）就报告过 `Connection refused`。先确认插件正在监听，以及主机、端口与配置一致。
- Claude 找不到 `uvx`。这是 README 写明的情况，请把 `command` 换成 `which uvx` 得到的绝对路径。
- 与 `mcp` Python SDK 2.0 不兼容。README 要求 `mcp>=1.1.0,<2.0.0`。若按未加约束的 `mcp>=2.0` 安装，会在导入时出现 `AttributeError: 'Server' object has no attribute 'list_tools'`。[issue #155](https://github.com/MarkusPfundstein/mcp-obsidian/issues/155) 和 [issue #156](https://github.com/MarkusPfundstein/mcp-obsidian/issues/156) 记录过同一类失败（均已关闭，并以 README 中的版本约束为准）。
- 路径处理上的安全报告。[issue #150](https://github.com/MarkusPfundstein/mcp-obsidian/issues/150)（2026-11-15 仍为 open）报告文件路径可能被拼到预期库范围之外。本文不复述复现步骤。在该问题仍开放时，更应使用隔离测试库，不要把生产库令牌交给不可信的代理环境。
- `delete_file` 和写入类工具默认可用。若你只想查询，应在客户端关闭这些工具，或先不要把生产库接进去。

## FAQ

### 为什么必须先装 Local REST API 插件？

因为这个 MCP 服务器不直接读库目录，而是调用该插件的 HTTP 接口。插件没运行时，工具调用没有可用的后端。密钥也在插件设置里，不在 MCP 仓库里。

### 默认端口一定是 27124 吗？

官方写明：未指定时默认端口是 27124，默认主机是 `127.0.0.1`。若你在插件设置里改过，MCP 配置必须同步修改，否则会出现连接失败。

### 官方支持 Cursor 或 Claude Code 吗？

README 只详细写了 Claude Desktop 和 Docker。它没有提供 Cursor 或 Claude Code 的专用命令。若某个客户端使用标准的 `mcpServers` 配置，理论上可以沿用同一组 `uvx` 和环境变量，但本文不把这一点写成已经官方核验过的安装路径。

### 可以把令牌交给远程代理吗？

不建议。令牌能让持有者通过插件访问笔记库，包括读取和（在工具启用时）修改或删除。官方示例把服务跑在本机，并指向 `127.0.0.1`。生产库令牌不要放进远端或共享环境。

### 搜索或读取失败时先看什么？

先看 Obsidian 是否仍在运行、插件是否启用、密钥是否完整粘贴，以及主机端口是否一致。若服务器根本没有启动，再检查 `uvx` 路径和 `mcp` 包版本是否仍低于 2.0。

## 来源与许可

仓库 [MarkusPfundstein/mcp-obsidian](https://github.com/MarkusPfundstein/mcp-obsidian) 使用 MIT 许可。它依赖的 [Obsidian Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api) 是单独的社区插件。本文依据 2026-11-15 查阅的 README，用自己的话写成，供 CQBase 上下文库使用。若环境变量、Python 或 `mcp` 版本要求有变，以仓库 README 为准。

## 收录信息

- 作者: MarkusPfundstein
- 许可证: MIT
- 来源: https://github.com/MarkusPfundstein/mcp-obsidian
- 收录: 2026-11-15
- GitHub 星标: 4538（采集 2026-11-15）

