Server facts
Obsidian MCP Server
Project
- Author
- cyanheads
- Repository
- github.com/cyanheads/obsidian-mcp-server
- License
- Apache-2.0
- Category
- Memory & Knowledge
Tech
- Runtime / language
- nodeTypeScript
- Transports
- stdio
- Remote available
- No
- Authentication
- Not specified
Activity
- GitHub stars
- 695
- Last commit
- Data as of
Tags
- Frontmatter
- Markdown
- Note Editing
- Obsidian
- Typescript
Overview
Obsidian MCP Server gives MCP clients structured access to notes, metadata, and editing operations in an Obsidian vault. Notes can be read as raw Markdown, a full structured object, a document map, or an individual section. Document maps expose headings, blocks, and frontmatter fields that other tools can target without replacing an entire file. Search supports text and JSONLogic, with BM25-ranked Omnisearch available when its plugin HTTP service is reachable. Results use cursor pagination, and file listings support filters and bounded recursive traversal.
Editing includes appending, section patches, sequential literal or regex replacements, frontmatter changes, and tag reconciliation. Whole-file writes refuse to overwrite an existing note unless explicitly allowed. Deletion remains destructive, with interactive confirmation requested when the client supports it. Optional policies can restrict read and write paths or disable writes altogether; unset policies allow access throughout the vault. Tag aggregation is a notable exception because it remains vault-wide rather than following path narrowing. Command-palette discovery and execution are separately opt-in, since commands can have broad side effects. The README advertises stdio and streamable HTTP, and the input configuration supplies a Local REST API key setting. However, the supplied README excerpt does not include a complete runnable launch command, so a setup command cannot be reproduced from that source alone.
Install & configure
Requirements
- An Obsidian vault
- A Local REST API key as shown in the input configuration
- An MCP-compatible client
No install command stated in the README — see repo.
Not stated in the supplied README excerpt: a complete runnable installation or launch command. The structured configuration suggests npx, but no command is reproduced here because the spec requires a README command. The README supports stdio and streamable HTTP. Omnisearch requires its plugin HTTP service to be reachable.
Examples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Config file · macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Use Settings → Developer → Edit Config when available. Do not assume a Linux configuration path; check the client documentation for your platform. Remote servers use the app’s connector flow when supported, not the local stdio file shown here. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the Claude Desktop setup guideConfig file · Project: .cursor/mcp.json
User: ~/.cursor/mcp.json
The project path is relative to the workspace root. The tilde denotes your user home directory. Use Cursor’s MCP settings to confirm which configuration and scope your installed version is reading. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the Cursor setup guideConfig file · Workspace: .vscode/mcp.json
For user scope, use the “MCP: Open User Configuration” command if available. Do not guess a user configuration path across operating systems, profiles, containers, or remote workspaces; check the client documentation. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the VS Code setup guideConfig file · macOS/Linux: ~/.codeium/windsurf/mcp_config.json
Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json
Open the MCP configuration through Windsurf’s settings when possible to confirm the active file. Paths can differ in managed or future releases; check the client documentation if this location is not present. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the Windsurf setup guideConfig file · Project scope: .mcp.json at the repository root
The project file uses mcpServers. For user scope, use claude mcp add --scope user rather than assuming .mcp.json in your home directory is the user configuration. Check the client documentation for managed settings and storage details. Merge this example with existing settings; do not overwrite unrelated servers.
No install command stated in the README — see repo. Check the client documentation for a supported connection method.
Read the Claude Code setup guideExamples are translated from the published configuration. Supply your own credentials and verify requirements in the upstream README. Remote connectors are shown only where a supported configuration format is known.
Tools
Source: repository tool metadata and repository README. Tool descriptions are a documented snapshot, not a live capability check.
| Tool | What it does |
|---|---|
| obsidian_get_note | Read a note, document map, or selected section. |
| obsidian_list_notes | List notes and directories with depth and name filters. |
| obsidian_list_tags | List vault tags and usage counts, including hierarchical parents. |
| obsidian_open_in_ui | Open a vault file in Obsidian, optionally creating a missing file. |
| obsidian_search_notes | Search note content or metadata with cursor-based pagination. |
| obsidian_write_note | Create a note or replace content, including a targeted section. |
| obsidian_append_to_note | Append to a note or section; whole-file mode can create missing notes. |
| obsidian_patch_note | Append, prepend, or replace a heading, block, or frontmatter target. |
| obsidian_replace_in_note | Apply ordered literal or regex replacements within one note. |
| obsidian_manage_frontmatter | Read, set, or remove one frontmatter key atomically. |
| obsidian_manage_tags | List, add, or remove frontmatter and optional inline tags. |
| obsidian_delete_note | Delete a note, requesting confirmation when supported by the client. |
| obsidian_list_commands | Discover command-palette commands when explicitly enabled. |
| obsidian_execute_command | Run an Obsidian command by ID when explicitly enabled. |
Names, permissions, and defaults can change. Check the current upstream documentation before granting access.
Use cases
- Read a section of a note without loading the full document.
- Update headings or frontmatter without replacing the whole file.
- Search vault content with text or metadata predicates.
- Reconcile inline and frontmatter tags.
- Limit an assistant to a specific writable folder.
Strengths
- Structural note maps enable targeted edits.
- Existing files are protected from default whole-file overwrites.
- Supports read-only and folder-scoped policies.
- Optional Omnisearch integration adds ranked retrieval.
Limitations
- Tag listing remains vault-wide even with path restrictions.
- Deletion has no API-level undo in the supplied tool facts.
- The supplied README excerpt lacks a complete runnable setup command.
Frequently asked questions
Independent listing, not an affiliation or security review. Grant the least access needed and verify the upstream instructions before running code.
