Provides tools for managing notes within an Obsidian vault, organized by project, including creating, reading, appending, listing, and searching notes.
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 Write a note in this project called "Meeting notes" with today's action items."
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 server that gives Claude a per-project notes folder inside one local Obsidian vault.
Each project gets its own subfolder under <vault>/Projects/<project-slug>/. There is still a
single vault, so cross-project links and the graph view keep working — you never have to switch
vaults in Obsidian.
Tool | What it does |
| Report which project folder notes will go to, and how that was decided. |
| Create a note. Refuses to clobber an existing one unless |
| Read a note's full contents. |
| Append to the end of a note, creating it if absent. |
| List notes in the project, or across the whole vault with |
| Case-insensitive text search returning |
Every tool takes an optional project argument that overrides inference.
Related MCP server: mcp-obsidian-vault
An explicit project argument, if given.
Otherwise, walk up from the server's working directory to the nearest .git and use that
directory's name — so a call made from ~/Developer/Projects/foo/src/lib still resolves to
foo.
Otherwise, use the working directory's own name.
Names are slugified: Job Search becomes job-search.
If inference lands on a container directory (Developer, Projects, src, $HOME, …) the
server refuses to guess and asks for an explicit project. That is the intended behavior, not a
bug — guessing there would scatter notes into a folder named after nothing in particular.
In Claude Desktop, always pass project explicitly. Desktop spawns MCP servers with an
arbitrary working directory, so there is nothing meaningful to infer from. Claude Code inherits
its own working directory, so inference works there.
Variable | Default |
|
|
|
|
The vault itself must already exist — the server will not create one, since a bare directory is not a vault. Project subfolders are created on first write.
npm install
npm run build
npm testnpm test runs unit tests for path handling and project resolution, plus an end-to-end suite
that speaks real JSON-RPC to the built server over stdio against a temporary vault.
Claude Code (user scope, so it applies to every project):
claude mcp add --scope user obsidian -- node /path/to/obsidian-mcp/dist/index.jsClaude Desktop — in ~/Library/Application Support/Claude/claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/obsidian-mcp/dist/index.js"]
}
}
}Rebuild after changing src/; both clients run dist/.
A vault under ~/Documents (also ~/Desktop, ~/Downloads) sits in a TCC-protected
location. A sandboxed host can end up able to write into folders it created while still
being denied a listing of the vault root — which breaks scope: "vault" for
list_notes and search_notes while everything project-scoped works fine.
The server raises Permission denied reading … rather than reporting an empty vault, so
this is visible instead of silent. Two ways out:
Grant Full Disk Access to whatever runs the server (System Settings → Privacy & Security → Full Disk Access).
Or move the vault somewhere unprotected and set OBSIDIAN_VAULT_PATH, e.g.
~/Vaults/main.
Note names are resolved and checked against the project folder, so ../../etc/passwd and
absolute paths are rejected rather than written. Writes never leave <vault>/Projects/<slug>/.
Append markdown to the end of a note, creating it if absent. Use this for running logs instead of rewriting the whole note.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | Note name or subpath. | |
| content | Yes | Markdown to add at the end. | |
| project | No | Project name. Omit to infer it from the working directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden of behavioral disclosure. It explicitly reveals the create-if-absent behavior and implies mutation through 'Append'. It could add details about permissions or side effects, but the key behavioral trait is communicated.
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 wasted words. The primary action is front-loaded, followed immediately by the most important behavioral nuance and a usage directive.
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?
For a simple 3-parameter tool with no output schema, the description covers purpose, behavior, and usage context. It does not explicitly mention return values or error cases, but the tool is simple enough that these are not critical gaps.
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 baseline is 3. The description adds meaning beyond the schema by clarifying that the note parameter results in creation if absent, and by framing content as suitable for running logs. This enriches parameter understanding.
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 ('Append') and resource ('to the end of a note'), and clearly states the create-if-absent behavior. It also distinguishes itself from the alternative of rewriting the whole note, aligning with sibling tool write_note.
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?
'Use this for running logs instead of rewriting the whole note' provides explicit context for when to use this tool and an exclusion against a rewrite approach. It does not name the exact sibling tool, but the intent is clear enough for an agent to route correctly.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List note paths in the project's folder, or across the whole vault.
| Name | Required | Description | Default |
|---|---|---|---|
| scope | No | "project" stays in this project's folder; "vault" covers every note. | project |
| project | No | Project name. Omit to infer it from the working directory. |
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 clearly conveys a read-only enumeration action and the two scope choices, but it does not mention path format, sorting, recursion, or how project inference from the working directory behaves at runtime. This is adequate but not rich behavioral context.
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 front-loaded sentence with no filler: 'List note paths' appears immediately, and the scope alternatives are stated compactly. 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?
For a simple list tool with two optional parameters and no output schema, the description plus the fully-documented schema is nearly sufficient for correct invocation. It lacks an explicit contrast with search_notes but otherwise covers the essential action and scoping context.
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 for parameters is 100%, so the baseline is 3. The description reinforces the 'project' vs 'vault' scope semantic and the project-folder notion, but it adds no parameter details beyond what the schema already documents. It does not explain path formats or inference fallbacks beyond the schema description.
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 names a specific verb ('List') and resource ('note paths'), and introduces a meaningful scope distinction between the project folder and the whole vault. It is clear and unambiguous, though it does not explicitly differentiate itself from the sibling search_notes, which could also return note paths when filtering by content.
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 gives no guidance on when to prefer this tool over alternatives such as search_notes, and does not mention any prerequisites or exclusions. While the scoping options are clear, the agent is left to infer when listing is the appropriate operation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a note's full contents from the project's vault folder.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | Note name or subpath. | |
| project | No | Project name. Omit to infer it from the working directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
There are no annotations, so the description carries the burden of behavioral disclosure. It correctly indicates a read operation scoped to the vault, implying no modification, but it does not describe return format, error behavior for missing notes, or path resolution details.
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?
One clear, front-loaded sentence with no filler. It states the action, target, and scope succinctly, making it easy for an agent to parse quickly.
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 low complexity and full schema coverage, the description is sufficiently complete for a simple read operation. The absence of an output schema is partially mitigated by 'full contents,' though explicit return/error details would be even stronger.
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 parameters are already well documented. The description adds no parameter-specific information beyond 'full contents,' which is adequate but does not raise the score above the baseline.
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' the resource 'a note's full contents' and scopes it to the project's vault folder. It is distinct enough from the sibling list/search tools, though it does not explicitly name them.
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 phrase 'full contents' implicitly conveys use when the full note body is needed rather than metadata or search results, but there is no explicit guidance on when to use this tool versus siblings like list_notes or search_notes.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report which project folder notes will go to, and how that was decided. Use this to check the inference before writing.
| Name | Required | Description | Default |
|---|---|---|---|
| project | No | Project name. Omit to infer it from the working directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. The phrase 'Report' and 'before writing' clearly indicate a non-mutating, read-only operation that does not create or modify notes, and it promises an explanation of the decision rather than just a result. This usefully communicates the tool's side of the contract.
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 sentences deliver the core behavior and the intended usage moment with no filler. The most important information is front-loaded, and every word contributes to agent understanding.
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?
For a simple one-parameter, read-only tool with no output schema, the description is complete: it states what is reported, how the decision is surfaced, and when to use it. The schema covers the parameter, and the sibling tools provide enough surrounding context to place this operation in the workflow.
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 only parameter, 'project', is fully described in the schema (including the omit-to-infer behavior), so schema coverage is 100%. The description adds conceptual context by mentioning 'inference,' but it does not need to add parameter-level details since the schema already handles them.
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 a specific verb ('Report'), a concrete resource ('which project folder notes will go to'), and the method ('how that was decided'). It distinguishes itself from sibling note-manipulation tools by framing this as a pre-write decision check rather than a note operation.
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 explicitly says 'Use this to check the inference before writing,' giving a clear usage context tied to the write workflow. It does not explicitly name alternatives or exclusion cases, but the context is unambiguous enough for an agent to know when to invoke it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Case-insensitive text search over note contents, returning matching lines with their note path and line number.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum matches. | |
| query | Yes | Text to look for. | |
| scope | No | "project" stays in this project's folder; "vault" covers every note. | project |
| project | No | Project name. Omit to infer it from the working directory. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the behavioral disclosure burden. It does disclose meaningful behavior: case-insensitive matching and the result format. However, it does not mention result ordering, whether the query is plain text or regex, or how limit interacts with matching — leaving some behavior opaque.
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, front-loaded sentence that starts with the core action and immediately gives the result format. Every word earns its place, with no redundant 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?
For a simple search tool, the description plus schema covers the invocation needs: query behavior, return shape, default scope, and limit constraints. It is slightly incomplete only in not comparing with list_notes or explaining result ordering, but this is a minor gap given the tool's simplicity.
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 100% description coverage, so the baseline is 3. The description adds the case-insensitive detail but does not otherwise clarify parameter semantics beyond what the schema already provides for query, limit, scope, and project.
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 a specific verb and resource: 'Case-insensitive text search over note contents'. It also defines the return shape ('matching lines with their note path and line number'), which makes the tool's function precise and distinguishable from the sibling tools like list_notes or read_note.
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: use this when you need to find text within note contents rather than listing or reading notes. However, it does not explicitly mention alternatives or when not to use this tool, leaving the agent to infer routing from sibling names and 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 in the project's vault folder. Refuses to clobber an existing note unless overwrite is true. Creates the project folder on first write.
| Name | Required | Description | Default |
|---|---|---|---|
| note | Yes | Note name or subpath, e.g. "decisions" or "meetings/kickoff". | |
| content | Yes | Markdown body of the note. | |
| project | No | Project name. Omit to infer it from the working directory. | |
| overwrite | No | Replace the note if it already exists. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing the non-clobbering default, the overwrite escape hatch, and automatic project folder creation. These are meaningful behavioral details beyond a simple 'create a note' statement.
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?
Three short sentences with no filler. The primary action is front-loaded, and the overwrite and folder-creation behaviors are stated economically without redundancy.
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?
For a write tool with no output schema and no annotations, the description covers the main action, the clobbering edge case, and the folder-creation side effect. It could mention return behavior or explicitly route to append_note for existing notes, but the core usage is adequately covered.
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 already describes all four parameters, so the baseline is 3. The description adds value by explaining the overwrite behavior and the automatic folder creation tied to the project parameter, which enriches understanding beyond the raw 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 opens with a specific verb and resource: 'Create a note in the project's vault folder.' It clearly differentiates the tool from siblings like append_note, read_note, and search_notes because it focuses on creation behavior.
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 clearly implies that this tool is for creating notes, but it does not explicitly state when to prefer append_note or another sibling. It gives behavioral context such as refusing to overwrite, but no direct when-to-use vs. alternatives guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool serves a clearly distinct purpose: resolving project routing, writing, reading, appending, listing, and searching notes. Even write_note and append_note are well differentiated by their overwrite and append semantics.
All tool names follow a consistent verb_noun snake_case pattern: resolve_project, write_note, read_note, append_note, list_notes, search_notes. This makes the API predictable and easy to navigate.
Six tools is a well-scoped set for an Obsidian note management server. Each tool covers a distinct operation without redundancy or bloat.
The core note lifecycle is well covered: create/write, read, append, list, and search. Missing delete, move, or rename operations are noticeable gaps, but agents can still accomplish most note workflows.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Agent-native notes, tasks, dev-docs, vaults, sync & handoffs. MCP + OpenAPI dual surface.
Persistent docs and memory for AI agents — read, write, organize & search a shared workspace.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/achyuta0001/obsidian-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
