Best for
- Obsidian users already running the Local REST API plugin.
- MCP client users who need structured note search and surgical editing.
- Deployments that need vault access restricted by read and write folder allowlists.
O
obsidian-mcp-server
Community
Manage Obsidian knowledge bases through MCP.
GitHub source repository ↗
60FMRS · C
The source describes a focused MCP server for Obsidian vault reading, writing, searching, and surgical editing, with folder policies and a read-only switch. The Local REST API plugin and API key are mandatory prerequisites. Public HTTP deployments should configure authentication and tightly limit write access.
obsidian-mcp-server is an open-source MCP server maintained by cyanheads. It uses the Obsidian Local REST API to read, create, search, and surgically edit notes, tags, and frontmatter. It supports STDIO and Streamable HTTP, exposes 14 tools and 3 resources, is version 3.2.9, and is licensed under Apache-2.0.
Tools
obsidian_get_note
Reads a note as raw content, a full structured record, a document map, or a single section.
obsidian_list_notes
Lists notes and subdirectories under a vault path with recursive depth and filtering options.
obsidian_list_tags
Lists all tags across the vault with usage counts.
obsidian_list_commands
Lists Obsidian command-palette commands; requires OBSIDIAN_ENABLE_COMMANDS.
obsidian_search_notes
Searches the vault by text, JSONLogic, or BM25-ranked Omnisearch when available, with cursor pagination.
obsidian_write_note
Creates a note or replaces a specified section; replacing an existing whole file requires explicit overwrite.
obsidian_append_to_note
Appends content to a note or to a specified heading, block, or frontmatter field.
obsidian_patch_note
Appends, prepends, or replaces a heading path, block reference, or frontmatter field.
obsidian_replace_in_note
Performs literal or regular-expression search and replace within one note body.
obsidian_manage_frontmatter
Atomically gets, sets, or deletes one frontmatter key.
obsidian_manage_tags
Adds, removes, or lists tags in frontmatter, inline body syntax, or both.
obsidian_delete_note
Permanently deletes a note and requests human confirmation when the client supports elicitation.
obsidian_open_in_ui
Opens a file in the Obsidian application UI.
obsidian_execute_command
Executes an Obsidian command-palette command by ID; must be explicitly enabled.
Setup
Install and enable the Obsidian Local REST API plugin v4.0.0 or later, then generate an API key in its settings. Use Bun v1.3.11 or later, or Node.js v24 or later. Put OBSIDIAN_API_KEY in the client configuration; the default endpoint is http://127.0.0.1:27123. Alternatively, use npx or clone the repository and run bun install. For Streamable HTTP, run start:http; the default endpoint is http://127.0.0.1:3010/mcp.
claude_desktop_config.json
{"mcpServers":{"obsidian-mcp-server":{"type":"stdio","command":"bunx","args":["obsidian-mcp-server@latest"],"env":{"MCP_TRANSPORT_TYPE":"stdio","MCP_LOG_LEVEL":"info","OBSIDIAN_API_KEY":"your-local-rest-api-key"}}}}
Fit and risk
Not for
- Environments without the Obsidian Local REST API plugin installed and enabled.
- Teams seeking a cloud-native multi-user database or collaboration platform.
- Situations where note write access or local API-key management is unacceptable.
Required permissions
- Requires OBSIDIAN_API_KEY to access the Obsidian Local REST API.
- By default, the full vault is accessible; OBSIDIAN_READ_PATHS and OBSIDIAN_WRITE_PATHS can restrict folders.
- All writes can be disabled globally with OBSIDIAN_READ_ONLY=true.
- HTTP deployments support none, jwt, or oauth authentication; JWT mode requires MCP_AUTH_SECRET_KEY.
Risks and side effects
- Write tools can modify or delete vault content; obsidian_delete_note permanently deletes notes.
- Command-palette commands may be destructive and are disabled by default.
- An unauthenticated public HTTP deployment may let callers use the server's API key to access the vault.
- The HTTPS plugin endpoint uses a self-signed certificate and TLS verification defaults to false.
- The tag list and obsidian://tags resource are vault-wide and may expose tag names outside the read scope.
Troubleshooting
- Verify that the Local REST API plugin is enabled and is version 4.0.0 or later.
- Check OBSIDIAN_API_KEY and confirm OBSIDIAN_BASE_URL uses the port configured in Obsidian.
- For the HTTP plugin port, enable Non-encrypted (HTTP) Server; for HTTPS, OBSIDIAN_VERIFY_SSL is normally false for the self-signed certificate.
- If Omnisearch is unavailable, verify that its HTTP server is reachable and restart the MCP server to re-probe it.
- For path_forbidden errors, inspect the read/write allowlists and OBSIDIAN_READ_ONLY.
- For HTTP connection issues, check MCP_HTTP_HOST, MCP_HTTP_PORT, MCP_HTTP_ENDPOINT_PATH, and MCP_AUTH_MODE.
Use cases
Reading and organizing Obsidian notes through an MCP client.
Searching a personal knowledge base with text, JSONLogic, or Omnisearch.
Making targeted edits to headings, block references, tags, and frontmatter.
Creating, appending, replacing, or deleting notes within controlled folders.
Supported clients
Claude DesktopFull support
CursorFull support
VS CodeFull support