Provides tools to manage Obsidian vaults, including reading, writing, searching notes, listing files, and executing Obsidian CLI commands.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Obsidian CLI MCP Server list notes in my inbox folder"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
使用 TypeScript 实现的 stdio MCP Server，通过 Obsidian 官方 CLI 为 Claude Code、Codex 等 AI Agent 提供 Vault 操作能力。
本项目不直接读写 Vault 文件，也不通过 shell 拼接命令。所有操作均以参数数组调用 Obsidian CLI，并提供 Vault 锁定、命令权限、超时、输出限制及跨进程串行保护。
查询 Obsidian 及 CLI 状态
列出 Vault 内的文件和文件夹
读取、创建、覆盖、追加和前置写入笔记
将大段 Markdown 自动拆成 UTF-8 安全块写入
搜索笔记及匹配上下文
调用属性、链接、任务、模板、历史、插件和开发者命令
按配置允许删除、command、eval 等高权限操作
将 Server 硬锁定到指定 Vault
串行处理多个 Agent 或并发 MCP 请求
调用链如下：
Claude Code / Codex
│ stdio MCP
▼
Obsidian CLI MCP Server
│ FIFO + 跨进程锁
▼
Obsidian.com / obsidian
│ IPC
▼
正在运行的 ObsidianRelated MCP server: obsidian-mcp
Node.js 20 或更高版本
Obsidian 1.12.7 或更高版本的安装器
在 Obsidian 的“设置 → 常规”中启用“命令行接口”
调用时保持 Obsidian 桌面端运行
目标 Vault 已由 Obsidian 打开或管理
Windows 使用安装目录中的 Obsidian.com 作为终端重定向器。升级安装器后，应重新启用命令行接口并重启终端。
先验证官方 CLI：
obsidian version
obsidian vaults verboseSet-Location D:\Document\MyMCP\ObsidianCli
npm install
npm run check
npm test
npm run build构建入口为：
D:\Document\MyMCP\ObsidianCli\dist\index.js修改 TypeScript 源码后必须重新执行 npm run build，并重启 MCP 客户端会话。
在 Vault 或 Claude Code 项目根目录创建 .mcp.json。下面是锁定到 Dance 且允许全部 Obsidian CLI 能力的配置：
{
"mcpServers": {
"obsidian-cli": {
"command": "node",
"args": [
"D:\\Document\\MyMCP\\ObsidianCli\\dist\\index.js"
],
"env": {
"OBSIDIAN_CLI_COMMAND": "D:\\Apps\\Common\\Obsidian\\Obsidian.com",
"OBSIDIAN_DEFAULT_VAULT": "Dance",
"OBSIDIAN_LOCKED_VAULT": "Dance",
"OBSIDIAN_CLI_ALLOW_UNSAFE": "true",
"OBSIDIAN_CLI_EXTRA_COMMANDS": "*"
}
}
}
}MCP 配置中的环境变量值必须全部是字符串。特别是应写成 "true"，不能写成 JSON 布尔值 true，否则 Claude Code 会忽略整个 Server 配置。
从项目根目录验证：
claude mcp list
claude mcp get obsidian-cli预期状态：
obsidian-cli ... ✓ Connected修改 .mcp.json 或重新构建 Server 后，应退出并重新启动 Claude Code。
在受信任的项目中创建 .codex/config.toml：
[mcp_servers.obsidian-cli]
command = "node"
args = ['D:\Document\MyMCP\ObsidianCli\dist\index.js']
cwd = 'D:\Workspace\Ob\Dance\Dance'
enabled = true
required = true
startup_timeout_sec = 30
tool_timeout_sec = 60
default_tools_approval_mode = "approve"
[mcp_servers.obsidian-cli.env]
OBSIDIAN_CLI_COMMAND = 'D:\Apps\Common\Obsidian\Obsidian.com'
OBSIDIAN_DEFAULT_VAULT = "Dance"
OBSIDIAN_LOCKED_VAULT = "Dance"
OBSIDIAN_CLI_ALLOW_UNSAFE = "true"
OBSIDIAN_CLI_EXTRA_COMMANDS = "*"Codex 只会为受信任项目加载项目级 .codex/config.toml。修改配置或重新构建后，以目标 Vault 为工作区新建 Codex 线程。
MCP Server 负责提供操作能力，Skill 负责规定 Agent 的知识管理流程。当前 Dance 项目分别使用：
.claude/skills/curate-dance-vault/SKILL.md
.agents/skills/curate-dance-vault/SKILL.mdClaude Code 与 Codex 使用相同 Skill 内容，约束 inbox、atlas、workspace、archive、system 的数据流，并要求优先使用本 MCP，而不是 shell 文件操作。
工具 | 主要输入 | 用途 |
| 无 | 查询 Obsidian 版本及 CLI 连通性 |
|
| 查询总帮助或指定命令帮助 |
|
| 列出 Vault、文件或文件夹 |
|
| 按 Vault 相对路径读取笔记 |
|
| 创建、追加或前置写入笔记 |
|
| 搜索笔记内容 |
|
| 执行其他允许的 Obsidian CLI 命令 |
obsidian_write_note.mode 支持：
create
append
prepend
obsidian_write_note 会把正文拆成最多 1,024 UTF-8 字节的块，并在一个不可交错的 CLI 批次中完成写入。调用方仍只需提交一次完整正文。
obsidian_cli 的参数格式：
{
"command": "move",
"parameters": {
"path": "inbox/source.md",
"to": "archive/source.md"
},
"flags": []
}Server 会将 Vault 参数放在命令之前，并将普通参数转换为 key=value。Obsidian 的普通布尔开关使用裸 flag，例如 overwrite、verbose；全局复制选项使用 --copy。
环境变量 | 默认值 | 说明 |
|
| CLI 可执行文件名或绝对路径 |
| 未设置 | 工具调用未指定 Vault 时使用的默认值 |
| 未设置 | 将 Server 硬锁定到指定 Vault，并禁止枚举所有 Vault |
|
| 单个进程的执行超时，范围 1–300 秒 |
|
| 单次调用最大输出，最高 10 MiB |
|
| 允许已知高影响命令 |
| 未设置 | 额外命令名，逗号分隔； |
同时设置默认和锁定 Vault 时，两者必须一致，否则 Server 拒绝启动。
OBSIDIAN_DEFAULT_VAULT=Dance
OBSIDIAN_LOCKED_VAULT=Dance
OBSIDIAN_CLI_ALLOW_UNSAFE=falseOBSIDIAN_DEFAULT_VAULT=Dance
OBSIDIAN_LOCKED_VAULT=Dance
OBSIDIAN_CLI_ALLOW_UNSAFE=true
OBSIDIAN_CLI_EXTRA_COMMANDS=*完全信任配置允许 delete、eval、command、插件管理、发布、恢复、主题及开发者命令，但仍不会把输入交给操作系统 shell。eval 和插件命令本身仍可能对 Obsidian 应用或 Vault 产生广泛影响。
使用 spawn(executable, argv, { shell: false })
校验命令、参数名和 flag 格式
默认使用安全命令白名单
高影响命令需要 OBSIDIAN_CLI_ALLOW_UNSAFE=true
未知或插件命令需要显式加入额外白名单，或设置 OBSIDIAN_CLI_EXTRA_COMMANDS=*
限制进程执行时间和输出大小
拒绝超过安全请求头大小的通用 CLI 调用；长正文必须使用 obsidian_write_note
设置 OBSIDIAN_LOCKED_VAULT 后：
所有未指定 Vault 的命令自动使用锁定值
显式指定其他 Vault 会返回错误
obsidian_list type=vaults 和通用 vaults 命令被禁用
Vault 锁定只约束通过本 Server 执行的命令。高权限的 Obsidian 应用级操作，例如插件安装或 eval，仍需由可信 Agent 使用。
Windows Obsidian.com 通过 IPC 与 Obsidian 主进程通信。多个 CLI 进程同时发送消息可能导致主进程 JSON 边界损坏。
Server 使用两层保护：
每个 MCP Server 内部的 FIFO Promise 队列。
临时目录中的跨进程锁，并使用心跳与失效锁恢复。
因此 Claude Code、Codex 和并发 MCP 工具调用会依次访问 Obsidian CLI。直接在终端运行的 obsidian 命令不会经过此锁，Agent 工作期间不要在其他终端并行执行大量 CLI 命令。
No MCP servers configured检查：
Claude Code 是否从包含 .mcp.json 的项目根目录启动。
.mcp.json 是否为有效 JSON。
env 下所有值是否都是字符串。
项目 MCP Server 是否已获准启用。
运行：
claude mcp list
claude mcp get obsidian-cli修改后重启 Claude Code。
Unexpected token ... is not valid JSON这表示 Windows CLI IPC 收到了损坏的 JSON 请求头。已确认的触发因素包括单次 content= 正文过大，以及多个 CLI 进程并行发送消息。当前 Server 会自动分块正文、限制通用请求大小并串行执行。
处理步骤：
确认已使用包含 FIFO 和跨进程锁的最新构建。
执行 npm run build。
完全退出 Claude Code、Codex 和 Obsidian。
先重新启动 Obsidian，再启动 Agent。
不要从其他终端并行运行 Obsidian CLI。
Agent 不应在 MCP 写入失败后降级到系统 Write 或 shell；这会绕过 Obsidian 和 Skill 的数据流规则。
跨进程锁异常退出后会自动恢复失效锁。
The CLI is unable to find Obsidian.确认：
Obsidian 正在运行
安装器为 1.12.7+
命令行接口已重新启用
MCP 进程与 Obsidian 运行在同一 Windows 用户和会话中
OBSIDIAN_CLI_COMMAND 指向正确的 Obsidian.com
MCP 客户端运行的是 dist/，不是 src/。执行：
npm run check
npm test
npm run build然后重启 Claude Code/Codex 会话。
npm run dev项目结构：
src/
commands.ts 命令白名单、参数与 flag 构造
config.ts 环境变量解析和 Vault 锁定配置
content.ts UTF-8 安全正文分块
runner.ts 进程执行、FIFO 与跨进程锁
server.ts MCP 工具注册
index.ts stdio 入口
test/
commands.test.ts
config.test.ts
content.test.ts
runner.test.ts
server.test.tsstdio 的标准输出专用于 MCP 协议；Server 日志只能写入标准错误。
npm run check
npm test
npm run build当前测试覆盖：
参数构造与 shell 注入边界
安全、危险及通配命令权限
Vault 锁定配置
CLI 退出码、超时与输出限制
单进程及跨 Runner 串行执行
MCP 工具发现
Advanced escape hatch for official Obsidian CLI features not covered by a dedicated tool. Arguments are passed directly without a shell.
| Name | Required | Description | Default |
|---|---|---|---|
| flags | No | Bare CLI flags such as verbose or the global --copy option | |
| vault | No | Vault name; overrides OBSIDIAN_DEFAULT_VAULT | |
| command | Yes | Obsidian CLI command name | |
| parameters | No | CLI key=value parameters |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Describes that arguments are passed without a shell (a safety warning), but does not disclose potential destructive actions, authorization needs, or side effects. Adequate but not comprehensive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences, front-loaded with purpose, no wasted words. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
No output schema, so description could mention return value (stdout). However, for a generic CLI runner, the description is fairly complete given the schema and annotations. Slight deduction for missing return clarification.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 4 parameters with details. The description adds no new parameter semantics beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's an 'advanced escape hatch' for Obsidian CLI commands not covered by dedicated tools, with specific mention of passing arguments directly without a shell. This distinguishes it from sibling tools like obsidian_read_note or obsidian_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says to use when a feature is 'not covered by a dedicated tool', implying when-not-to-use. Provides context on argument passing (no shell). Sibling tools are listed but not directly compared, so a slight deduction.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return official CLI help. Optionally provide a command to inspect its current parameters and flags.
| Name | Required | Description | Default |
|---|---|---|---|
| command | No | CLI command to inspect, for example search or property:set |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the burden. It correctly describes the tool as returning help text and inspecting command parameters. No contradictions or omissions for this simple read-only tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, focused sentences with no wasted words. The key information is presented efficiently and upfront.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the simplicity of this help tool with one optional parameter and no output schema, the description is adequate. It could mention that output is text, but not necessary.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema provides 100% coverage with a clear description and pattern. The tool description adds context that providing a command inspects 'its current parameters and flags', which enhances understanding beyond the schema alone.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool returns official CLI help, with an optional command to inspect parameters and flags. This differentiates it from siblings like obsidian_cli (which likely executes commands) and obsidian_list (listing notes).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description does not provide explicit guidance on when to use this tool versus alternatives. It only states the functionality but lacks context for decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List vaults, files, or folders known to Obsidian.
| Name | Required | Description | Default |
|---|---|---|---|
| type | Yes | ||
| vault | No | ||
| folder | No | ||
| extension | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It only says 'list', implying a read-only operation, but does not disclose any behavioral details such as authentication requirements, side effects, or error conditions. The description is too brief to be transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence of 8 words, making it concise. However, it lacks any structural elements like examples or usage context. It is minimally adequate but not well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema, no annotations, and 4 parameters with 0% schema coverage, the description fails to provide complete context. It does not describe return values, parameter dependencies, or error conditions, leaving gaps for the agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% parameter description coverage, and the tool description does not explain any parameters (type, vault, folder, extension). The description adds no meaning beyond the schema's property names and enum values.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it lists vaults, files, or folders, using the verb 'list' and specifying three resource types. It distinguishes from sibling tools (obsidian_read_note, obsidian_write_note, etc.) which perform different actions. However, it could be more precise about what 'known to Obsidian' means.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives (e.g., obsidian_search for searching notes). It does not mention prerequisites or context, leaving the agent to guess.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a note from an Obsidian vault by vault-relative path.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path | |
| vault | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It does not disclose any behavioral traits such as whether the note must exist, read permissions needed, or what happens on error. Minimal disclosure.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with clear structure, front-loading the action and the key identifier (vault-relative path). No unnecessary words, but could be slightly expanded without losing conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no output schema and minimal description, agent lacks info on return format, error handling, and the role of the vault parameter. Incomplete for a read operation, though complexity is low.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 50% (only 'path' has description). Description adds no extra meaning beyond schema. The 'vault' parameter lacks any description, and the description does not explain the relationship between vault and path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states tool reads a note from an Obsidian vault by vault-relative path. Verb 'read' is specific and resource 'note' is distinct from sibling tools like obsidian_write_note or obsidian_list.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives like obsidian_search or obsidian_list. Missing context on usage scenarios or prerequisites.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search note contents and return matching files or contextual matches.
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | ||
| limit | No | ||
| query | Yes | ||
| vault | No | ||
| format | No | json | |
| context | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description does not disclose behavioral traits beyond the basic purpose. It fails to mention that the tool is read-only, does not describe the return format (e.g., file paths, snippets), and gives no details on search behavior like exact vs fuzzy matching. With no annotations, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise (one short sentence), but this brevity sacrifices necessary detail. It avoids fluff, but is too minimal to be effective.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 6 parameters, no annotations, and no output schema, the description is severely incomplete. It does not explain return values, parameter interactions, or edge cases, leaving an AI agent without enough context to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 6 parameters with 0% description coverage, and the description adds no information about what parameters like 'path', 'limit', 'vault', 'format', or 'context' do. The description only implies 'query' is the search term, but does not explain syntax or constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches note contents and returns matching files or contextual matches, distinguishing it from sibling tools like obsidian_list and obsidian_read_note. However, 'contextual matches' is somewhat vague.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives like obsidian_list or obsidian_read_note. There is no mention of prerequisites, exclusions, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Check whether the Obsidian CLI is reachable and return its version.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It states a read-only check and version return but does not detail error behavior, network dependencies, or whether it modifies state. Adequate for a simple status check, but lacking depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single, complete sentence with no unnecessary words. Every part is meaningful and efficiently conveys the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no parameters, no output schema, and no annotations, the description sufficiently explains the basic action. However, it could specify whether the output is a version string or an error on failure for greater completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
No parameters exist (schema coverage 100%), so the description does not need to add parameter info. It meets the baseline expectation for a tool with zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Check') and resource ('Obsidian CLI'), clearly stating it checks reachability and returns version. This distinguishes it from sibling tools like obsidian_list or obsidian_write_note, which have different purposes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives, such as before performing other operations to verify CLI availability. The description solely states what it does without context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a note or append/prepend content. Existing files are overwritten only when overwrite=true.
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | create | |
| path | Yes | Vault-relative note path | |
| vault | No | ||
| content | Yes | Markdown content to write | |
| overwrite | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It explains the three modes (create, append, prepend) and the overwrite flag behavior. However, it omits details on error handling when a file exists with overwrite=false, or any permission or side-effect information.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: two sentences, no fluff, and front-loaded with the core action. Every word contributes meaning.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the moderate complexity (5 params, no output schema), the description covers the main use cases but lacks details on edge cases, error modes, and return behavior. It is adequate but not fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 40%, so the description should compensate but does not. It mentions modes and overwrite, but these are already in the schema. The tool has 5 parameters, and the description adds little semantic value beyond the schema's own descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Create a note or append/prepend content.' It specifies the verb (create, append, prepend) and resource (note), distinguishing it from sibling tools like obsidian_read_note and obsidian_list. It is specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides implicit context for when to use the tool (to create or modify notes) but lacks explicit guidance on when not to use it or comparisons with alternatives. It mentions the overwrite behavior but does not address prerequisites or failure modes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0obsidian_cliobsidian_helpobsidian_listobsidian_read_noteobsidian_searchobsidian_statusobsidian_write_noteScored across 7 tools
Each tool has a clearly distinct purpose: listing, reading, writing, searching, status, help, and a generic escape hatch. No overlap or ambiguity.
All tools follow the consistent pattern 'obsidian_<action>' with snake_case, making it predictable for the agent.
Seven tools is well-scoped for an Obsidian CLI wrapper, covering essential operations without being excessive or insufficient.
Covers core CRUD (read, write), search, list, status, and help. Missing explicit delete or rename, but the escape hatch fills gaps.
Securely search and manage workspace context files for AI agents and teams.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…