Allows reading, writing, searching, and organizing notes in an Obsidian vault directly via the filesystem, with automatic syncing when Obsidian is open.
Click on "Install 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-mcp list my notes in the Projects 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.
An MCP (Model Context Protocol) server that lets AI coding agents (Claude Code, Codex CLI, etc.) read, write, search, and organize notes in an Obsidian vault. It works directly on the filesystem, so Obsidian doesn't need to be running — Obsidian picks up external changes automatically.
Community project — not affiliated with Obsidian.
git clone https://github.com/Mochiduki-0715/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run buildConfiguration is done through environment variables:
Variable | Description | Default |
| Absolute path to your vault folder | (required) |
| Folder for daily notes, relative to the vault root |
|
| Folder for templates, relative to the vault root |
|
Related MCP server: Obsidian MCP Server
claude mcp add --scope user obsidian \
--env OBSIDIAN_VAULT_PATH=$HOME/path/to/your/vault \
-- node /path/to/obsidian-mcp/dist/index.jsAdd to ~/.codex/config.toml:
[mcp_servers.obsidian]
command = "node"
args = ["/path/to/obsidian-mcp/dist/index.js"]
[mcp_servers.obsidian.env]
OBSIDIAN_VAULT_PATH = "/path/to/your/vault"Tool | Description |
| List notes, newest first; optionally restricted to a subfolder |
| Read a note, returning parsed frontmatter and the markdown body |
| Create a note (pass |
| Append text; with |
| Edit by exact string replacement ( |
| Update YAML frontmatter by key: merge |
| Case-insensitive full-text search, with optional |
| Move/rename a note and rewrite |
| Move a note to the vault's |
| List notes that link to a given note, with file/line/link-type |
| Get or create the daily note for today or a given date |
| Get a note's heading outline (level/text/line) and line count, skipping code fences |
| Create a note from a template in |
npm testRuns the TypeScript build followed by Node's built-in test runner
(node --test) against the compiled dist/*.test.js files.
Every path is resolved inside the vault root; .. escapes are rejected
Deleting moves notes to Obsidian's standard .trash/ folder instead of removing them
create_note never silently overwrites an existing note (an explicit flag is required)
Append text to a note. With 'heading', the text is inserted at the end of that heading's section (the section is created if missing).
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path | |
| text | Yes | Markdown text to append | |
| heading | No | Insert under this heading instead of at the end of the file | |
| create_if_missing | No | Create the note if it does not exist (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that with 'heading', the section is created if missing, but does not explain default behavior for missing notes (relies on create_if_missing parameter), error cases, or idempotency. Some behavioral traits are disclosed but gaps remain.
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 sentences with no fluff. The first sentence clearly states the core action, and the second adds a necessary behavioral nuance. Every word earns its place.
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 4 parameters and no output schema, the description covers core behavior but omits details about return values, error conditions (invalid path, missing heading), and default behavior when create_if_missing is false. Adequate but leaves gaps for a first-time user.
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%, baseline 3. The description adds value by explaining the heading insertion behavior in prose, including that the section is created if missing, which is more detailed than the schema description for 'heading'. This extra context earns a higher score.
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 'Append text to a note', a specific verb-resource pair. This distinguishes it from siblings like create_note or edit_note, which have different actions. The additional detail about heading sections further clarifies its unique functionality.
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 implies usage for appending text, but does not explicitly state when to use this tool versus alternatives like edit_note or create_note. No guidance on when not to use or conditions like note existence.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a new markdown note (parent folders are created automatically). Fails if the note exists unless overwrite is true.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path | |
| content | Yes | Full markdown content, including optional YAML frontmatter | |
| overwrite | No | Replace the note if it already exists (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description encodes key behaviors: automatic parent folder creation and failure on existing note unless overwrite is true. This provides sufficient transparency for a simple file creation tool, though authorization or rate limits are not discussed.
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 two sentences, front-loading the purpose and adding critical behavior details without any wasted words.
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 the tool and complete schema coverage, the description covers the key creation behavior. It does not specify return value, but for a create operation this is often implied.
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 100%, and the description adds value by explaining that parent folders are created automatically (path) and that the operation fails if the note exists unless overwrite is true (overwrite). This goes beyond the schema 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 creates a new markdown note. It distinguishes from siblings like edit_note and append_note by emphasizing creation of a new note with automatic folder creation and existence check.
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 clear context on when to use (creating a new note) and the behavior when a note already exists. It does not explicitly mention alternatives, but sibling tool names are available for reference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Edit a note by exact string replacement. Fails if old_text is not found, or is ambiguous without replace_all.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path | |
| new_text | Yes | Replacement text | |
| old_text | Yes | Exact text to replace | |
| replace_all | No | Replace every occurrence (default false) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses failure conditions and replacement behavior. Without annotations, description carries full burden; it adequately warns about ambiguity and strict matching.
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 sentences, front-loaded with verb and method, no redundant words. Every sentence serves a purpose.
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?
Despite no output schema or annotations, description covers key behavioral aspects (failure, replacement). Could mention if operation is reversible or return value, but adequate for simple edit.
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 covers all parameters with descriptions, but description adds context on failure conditions and exact replacement semantics, beyond what schema provides.
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 specifies exact string replacement, clearly distinguishing from sibling tools like update_frontmatter (metadata) and append_note (appending). Verb+resource+method are specific.
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?
Indicates failure conditions (old_text not found, ambiguous without replace_all), guiding when to use the replace_all parameter. No explicit exclusion of siblings, but context is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List markdown notes in the Obsidian vault, sorted by last modified (newest first). Optionally restrict to a subfolder.
| Name | Required | Description | Default |
|---|---|---|---|
| folder | No | Vault-relative subfolder to list, e.g. 'Daily'. Omit for the whole vault. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses sorting order and optional subfolder filtering. No annotations provided, but description adequately conveys read-only listing behavior. No mention of performance or rate limits, but acceptable for a simple list 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?
Single sentence, front-loaded with key action and parameters, no filler.
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 tool's simplicity (one optional param, no output schema), the description covers listing purpose and constraints. Could mention return format, but not critical.
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 100% with description. Description adds sorting info and the 'optionally restrict' nuance, providing value 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?
Description states 'List markdown notes' with sorting and optional subfolder restriction. Clearly differentiates from siblings like create_note, read_note, etc.
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?
Clear context: use to get a list of notes, optionally filtered by subfolder. Lacks explicit when-not-to-use or alternatives, but context is sufficient.
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 the vault. Returns the parsed frontmatter and the markdown body.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Vault-relative note path, e.g. 'Projects/idea' or 'Projects/idea.md' |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It correctly describes the return value (frontmatter and markdown body) and implies read-only behavior via the verb 'Read'. However, it does not explicitly state that the tool has no side effects or that it will error if the path does not exist.
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 with two sentences. The first sentence states the action, and the second specifies the return content. No extraneous information, 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?
The description adequately covers the tool's purpose and output for a simple read operation. It lacks details about error conditions (e.g., missing note) and authentication requirements, but these are not critical given the simplicity and the presence of a well-documented parameter.
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 already provides a complete description of the single parameter 'path' (including an example). The tool description does not add additional meaning beyond what the schema offers, so a baseline score of 3 is appropriate.
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 action ('Read a note') and the resource ('from the vault') and specifies the output (parsed frontmatter and markdown body). It distinguishes from sibling tools like update_frontmatter, list_notes, create_note, append_note, and edit_note, which all involve modification or listing.
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 clear context for when to use this tool (to read a note's content) but does not explicitly state when not to use it or mention alternative tools. This is acceptable but lacks explicit exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Update a note's YAML frontmatter by key: merge set values (added or overwritten) and delete remove keys. The note body is left untouched.
| Name | Required | Description | Default |
|---|---|---|---|
| set | No | Keys to add or overwrite, merged into existing frontmatter | |
| path | Yes | Vault-relative note path | |
| remove | No | Keys to delete from frontmatter |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations present; description discloses that note body is left untouched. However, it does not mention error handling, permission requirements, or atomicity.
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 clear sentence with immediate verb and resource. No extraneous text. Key actions (merge set, delete remove) are front-loaded.
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?
Tool has only 3 parameters and no output schema. Description covers the core behavior (updating frontmatter without touching body). Minor gaps: no mention of return value or error cases.
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 100%. Description adds 'merged into existing frontmatter' for set and 'Keys to delete' for remove, providing context beyond schema property 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?
Description uses specific verb 'Update' and resource 'YAML frontmatter', clearly distinguishing from sibling tools that modify note body or create/read 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?
No explicit when-to-use or when-not-to-use guidance. Sibling tools are listed but not referenced. Implicitly, it's for frontmatter modifications only.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct action: listing, reading, creating, appending, editing, and updating frontmatter. No two tools overlap in purpose.
All tool names follow a consistent verb_noun snake_case pattern (e.g., list_notes, create_note, update_frontmatter).
With 6 tools, the set is well-scoped for managing notes in a vault, covering essential operations without being overwhelming.
The set covers create, read, and update operations, but notably lacks a delete tool, which is a significant gap for full lifecycle management.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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…
Securely search and manage workspace context files for AI agents and teams.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Mochiduki-0715/obsidian-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server