1. 为什么你的 Obsidian MCP 总是连不上如果你正在用 Claude Desktop、Cline 或者任何支持 MCP 的客户端去读 Obsidian 笔记大概率会遇到一个很别扭的问题客户端里明明配好了obsidian-mcp但一调用query_dataview就报错或者干脆连list_vault都返回空。这不是你的笔记库有问题而是 Local REST API 这一层的 endpoint 和认证没对齐。obsidian-mcp 本质上是一个“翻译层”。它自己不直接读你的 vault而是通过 Obsidian 里的 Local REST API 插件暴露的 HTTPS 接口去拿数据再把结果包装成 MCP 工具返回给模型。所以链路是MCP 客户端 → obsidian-mcpstdio→ Local REST APIHTTPS→ Obsidian Vault。任何一环的地址、端口、协议、API Key 写错都会表现为“MCP 服务无响应”。这篇内容聚焦一个具体场景你已经装好了 obsidian-mcp现在要把 Local REST API 的 endpoint 和 API Key 正确接进去并且用一次 Dataview 查询来验证整条链路是通的。适合谁适合已经在用 Obsidian 做知识管理、想让 AI 代理帮你做图遍历、孤立笔记清理、每日笔记跟进的用户。不适合完全没碰过 MCP 配置的小白但我会把每一步都写清楚照着做就能跑。核心检索词先摆出来obsidian-mcp 是什么它是一个把 Obsidian vault 当作知识图谱来访问的 MCP 服务支持 15 个工具包括get_note、query_dataview、traverse_graph、find_orphans等。能做什么让 Claude 或任何 MCP 客户端直接查询你的 Dataview DQL、遍历双向链接、追加每日笔记。适合谁适合用 Obsidian 管理项目、做内容地图、清理孤立笔记的人。我试过在 macOS 和 Windows 上分别配一遍踩过的坑主要集中在端口协议和 TLS 验证上。下面按“原问题 → 前置准备 → 可复制配置 → 验证请求 → 错排查 → CTA”的顺序展开你可以直接跳到对应章节。2. obsidian-mcp 与 Local REST API 的前置准备在改配置之前先把三个东西确认好Obsidian 必须开着、Local REST API 插件必须启用、Dataview 插件必须装好。这三个缺一个后面的验证都会失败。2.1 确认 Local REST API 的 endpoint 与端口Local REST API 插件在 Obsidian 内部跑一个 HTTPS 服务器默认监听127.0.0.1。端口有两个协议默认端口说明HTTPS27124默认使用自签名证书HTTP27123需要手动开启不推荐obsidian-mcp 默认走 HTTPS 27124。如果你在插件设置里改过端口后面配置里的OBSIDIAN_PORT必须跟着改。我建议保持默认因为 obsidian-mcp 的默认值就是按这个来的少改少错。打开 Obsidian → 设置 → Community plugins → Local REST API你会看到两个关键信息一个是 API Key一长串一个是端口号。把 API Key 复制出来后面要填到环境变量里。注意Local REST API 插件必须在 Obsidian 运行时才生效。如果你关了 ObsidianMCP 服务会直接报连接拒绝。这不是配置错误是设计如此。2.2 确认 Dataview 插件已启用query_dataview这个工具依赖 Dataview 插件。如果你没装 Dataview调用它会返回“Dataview plugin not available”之类的错误。装好之后在 Obsidian 设置 → Dataview 里确认“Enable Dataview”是打开的。Dataview 的 DQL 查询语法不需要你额外配置obsidian-mcp 会把查询语句透传给插件执行。2.3 确认 Node.js 版本obsidian-mcp 通过npx启动需要 Node.js v16 或更高。在终端里跑node -v如果低于 v16先去升级。Windows 用户如果没装 Node去官网下 LTS 版本即可。这一步不涉及任何网络工具就是本地运行时。2.4 理解环境变量表obsidian-mcp 支持以下环境变量配置时按需填写变量名必需默认值说明OBSIDIAN_API_KEY是-从 Local REST API 插件设置获取OBSIDIAN_HOST否127.0.0.1Obsidian 主机地址OBSIDIAN_PORT否27124 (https) / 27123 (http)端口号OBSIDIAN_PROTOCOL否https协议类型OBSIDIAN_VERIFY_TLS否false是否验证 TLS 证书OBSIDIAN_TIMEOUT_MS否15000请求超时时间毫秒关键点OBSIDIAN_VERIFY_TLS默认是false因为 Local REST API 用的是自签名证书。如果你把它改成true又没有把自签名证书加入信任链就会报 TLS 错误。流量只在本地回环验证 TLS 没有实际安全收益保持false就行。3. 可复制的 obsidian-mcp 配置片段这一章给出完整的配置文件片段包括 Claude Desktop 的claude_desktop_config.json、Cline 的 MCP 配置以及一个通用的 JSON 模板。你直接复制、替换 API Key 就能用。3.1 Claude Desktop 配置macOS编辑文件~/Library/Application Support/Claude/claude_desktop_config.json{ mcpServers: { obsidian: { command: npx, args: [-y, obsidian-mcp], env: { OBSIDIAN_API_KEY: paste-your-key-here, OBSIDIAN_HOST: 127.0.0.1, OBSIDIAN_PORT: 27124, OBSIDIAN_PROTOCOL: https, OBSIDIAN_VERIFY_TLS: false, OBSIDIAN_TIMEOUT_MS: 15000 } } } }把paste-your-key-here换成你从 Local REST API 插件里复制的 API Key。注意 JSON 里不能有注释Key 要用双引号包起来。3.2 Claude Desktop 配置Windows编辑文件%APPDATA%\Claude\claude_desktop_config.json{ mcpServers: { obsidian: { command: npx, args: [-y, obsidian-mcp], env: { OBSIDIAN_API_KEY: paste-your-key-here, OBSIDIAN_HOST: 127.0.0.1, OBSIDIAN_PORT: 27124, OBSIDIAN_PROTOCOL: https, OBSIDIAN_VERIFY_TLS: false } } } }Windows 下%APPDATA%通常展开为C:\Users\你的用户名\AppData\Roaming。如果 Claude Desktop 没读到配置检查这个路径下有没有claude_desktop_config.json没有就手动建一个。3.3 Cline / Roo Code 的 MCP 配置如果你用 Cline 或 Roo CodeMCP 配置通常在 VS Code 的设置里格式类似{ mcpServers: { obsidian: { command: npx, args: [-y, obsidian-mcp], env: { OBSIDIAN_API_KEY: paste-your-key-here, OBSIDIAN_PORT: 27124, OBSIDIAN_PROTOCOL: https, OBSIDIAN_VERIFY_TLS: false } } } }Cline 的 MCP 配置文件路径一般在~/.cline/mcp_settings.json或 VS Code 的settings.json里。具体位置看你的 Cline 版本但 JSON 结构是一样的。3.4 多 vault 场景的配置obsidian-mcp 一个实例只指向一个运行中的 Obsidian 实例。如果你频繁切换 vault需要配多个 MCP 服务器条目用不同名称和不同端口区分{ mcpServers: { obsidian-work: { command: npx, args: [-y, obsidian-mcp], env: { OBSIDIAN_API_KEY: work-vault-key, OBSIDIAN_PORT: 27124 } }, obsidian-personal: { command: npx, args: [-y, obsidian-mcp], env: { OBSIDIAN_API_KEY: personal-vault-key, OBSIDIAN_PORT: 27125 } } } }每个 vault 在 Local REST API 插件里设置不同端口然后分别配 API Key。这样模型调用时可以通过服务器名称区分。3.5 关于 TaoToken 的接入位置如果你希望 MCP 客户端背后的模型调用走 TaoToken 的 API那是在客户端层面配置 Base URL 和 API Key而不是在 obsidian-mcp 里配。obsidian-mcp 只负责 Obsidian 这一侧的数据访问。模型侧的配置是另一套Base URLhttps://taotoken.net/apiAPI Key在 TaoToken 控制台创建Model ID按你需要的模型填这三件套要写全缺一个都会导致模型调用失败。obsidian-mcp 的配置和模型 API 的配置是两条独立的链路不要混在一起。4. 验证 Dataview 查询的连通性配置写完之后不要急着让模型做复杂操作。先用一次最简单的 Dataview 查询验证整条链路。这一步能帮你快速定位是 MCP 层的问题还是 Local REST API 层的问题。4.1 重启客户端并确认 MCP 服务加载Claude Desktop 需要完全退出再重启不是关窗口。macOS 下用CmdQWindows 下从托盘退出。重启后在对话里输入列出当前 vault 里所有 markdown 文件如果 obsidian-mcp 正常加载模型会调用list_vault并返回文件列表。如果返回“没有可用工具”或“MCP server not found”说明配置文件路径或 JSON 格式有问题。4.2 执行一次 Dataview DQL 查询确认list_vault能返回结果后再测试query_dataview。在对话里输入用 Dataview 查询所有带有 #project 标签且 status 不是 done 的笔记模型会调用query_dataview传入类似这样的 DQLTABLE status, due FROM #project WHERE status ! done SORT due ASC如果 Dataview 插件正常你会看到一张表格列出符合条件的笔记路径、status 和 due 字段。如果返回空先确认你的 vault 里确实有带#project标签的笔记并且这些笔记的 frontmatter 里有status字段。4.3 用 curl 直接验证 Local REST API如果 MCP 层一直报错可以绕过 obsidian-mcp直接用 curl 测 Local REST API 是否正常。这一步能帮你区分是插件问题还是 MCP 配置问题。curl -k -H Authorization: Bearer paste-your-key-here \ https://127.0.0.1:27124/vault/-k表示跳过 TLS 证书验证对应OBSIDIAN_VERIFY_TLSfalse。如果返回 JSON 格式的文件列表说明 Local REST API 正常问题在 obsidian-mcp 的配置。如果返回 401说明 API Key 错了。如果连接被拒绝说明 Obsidian 没开或端口不对。4.4 验证图遍历工具Dataview 通了之后可以再测一个图遍历从 Distributed systems.md 出发遍历 2 跳列出所有邻居笔记模型会调用traverse_graph参数是path: Distributed systems.md、depth: 2、direction: both。返回结果会包含节点和边。如果这个也通了说明 obsidian-mcp 的图感知工具全部可用。4.5 验证每日笔记追加最后测一下写入功能在今日每日笔记末尾追加一行MCP 连通性验证通过模型会调用append_to_daily_note。去 Obsidian 里打开今日笔记看末尾有没有这行字。如果有说明写入链路也通了。注意写入操作会真实修改你的 vault测试时用无关键内容。5. 常见报错与排查对照这一章列出真实会遇到的报错以及对应的排查方向。每条都按“报错原文 → 原因 → 解决”的结构写。5.1 401 Unauthorized报错原文Error: Request failed with status code 401原因API Key 不对或者请求头格式不对。Local REST API 要求Authorization: Bearer key。解决回到 Obsidian → 设置 → Local REST API重新复制 API Key。注意不要多复制空格。如果 Key 里有特殊字符JSON 里要正确转义。改完配置后重启客户端。5.2 local proxy failed / ECONNREFUSED报错原文Error: connect ECONNREFUSED 127.0.0.1:27124原因Obsidian 没开或者 Local REST API 插件没启用或者端口不对。解决确认 Obsidian 正在运行确认 Local REST API 插件是启用状态确认插件设置里的端口和配置里的OBSIDIAN_PORT一致。如果改了端口两边都要改。5.3 reading choices 报错报错原文TypeError: Cannot read properties of undefined (reading choices)原因这通常不是 obsidian-mcp 的问题而是模型 API 返回格式不对。如果你在客户端里配了自定义 Base URL可能返回的不是 OpenAI 兼容格式。解决检查模型侧的 Base URL 和 API Key。如果用 TaoTokenBase URL 填https://taotoken.net/apiKey 在控制台创建。确认 Model ID 拼写正确。这个报错和 Obsidian 无关是模型调用层的问题。5.4 OAuth 相关报错报错原文Error: OAuth token exchange failed原因某些 MCP 客户端在连接远程服务时会走 OAuth 流程。obsidian-mcp 是本地 stdio 服务不走 OAuth。解决确认你配的是command: npx的 stdio 模式而不是远程 URL 模式。如果你在客户端里填了远程地址改成 stdio 配置。5.5 Dataview plugin not available报错原文Error: Dataview plugin is not enabled原因Dataview 插件没装或没启用。解决Obsidian → 设置 → Community plugins → 安装并启用 Dataview。启用后不需要额外配置obsidian-mcp 会自动检测。5.6 TLS 证书错误报错原文Error: self signed certificate原因OBSIDIAN_VERIFY_TLS被设成了true但用的是自签名证书。解决把OBSIDIAN_VERIFY_TLS改回false。本地回环流量不需要 TLS 验证。5.7 工具调用超时报错原文Error: timeout of 15000ms exceeded原因vault 太大或者 Dataview 查询太复杂15 秒不够。解决把OBSIDIAN_TIMEOUT_MS调大比如30000。同时优化 Dataview 查询加LIMIT限制返回数量。5.8 配置三件套检查清单如果你用的是 Cline MCP 或 Codex 的auth.json确认以下三件套都写全了项目值Base URLhttps://taotoken.net/apiAPI Key在 TaoToken 控制台创建Model ID按需填写如claude-sonnet-4-20250514缺任何一个都会导致模型调用失败。obsidian-mcp 的OBSIDIAN_API_KEY和模型侧的 API Key 是两回事不要混淆。6. 把链路跑通之后的使用建议配置和验证都过了之后你可以开始让模型做实际的知识管理任务。这里给几个我实测下来比较顺手的用法。构建内容地图时用traverse_graph从某个主题出发深度设 2方向设both让模型把邻居按标签分组写入 MOC 笔记。这个操作比手动翻反向链接快很多。清理孤立笔记时先用find_orphans找出没有入链的笔记再让模型根据内容和现有标签建议归属位置。注意批量操作前先让模型列出它准备改哪些文件确认后再执行。每日笔记跟进时用get_daily_note拿今日笔记用search_vault找昨日未完成事项再用append_to_daily_note把跟进结果写回去。这个流程适合每天早上跑一次。如果你需要长期跑编码或 Agent 任务可以考虑 TaoToken 的 Coding Plan把模型调用和 MCP 工具链结合起来。模型对话调试可以去模型对话页面API Key 在控制台创建接入文档在文档页。这几个入口按需取用。最后提醒一句obsidian-mcp 授予模型的权限等同于 API Key 的权限。模型能删的笔记它真的会删。批量操作前一定先检查它即将执行的动作。