Obsidian MCP Server
Integrates with the Obsidian Local REST API to read, create, and edit notes, perform file and directory operations within a vault, and execute advanced searches using Dataview DQL or JsonLogic.
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 MCP Server Find my notes about 'Project Mars' and summarize the main points."
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.
Obsidian MCP Server
A modern Model Context Protocol (MCP) server that integrates with the Obsidian Local REST API to read, create, and edit notes effectively within Obsidian.
Features
This MCP server provides the following tools:
Vault File Operations
Tool | Description |
| Get file content (raw markdown, JSON with metadata, or document map) |
| Create or completely replace a file |
| Append content to an existing or new file |
| Partially update a file (heading/block/frontmatter operations) |
| Delete a file from the vault |
Directory Operations
Tool | Description |
| List files and directories in the vault |
Search Operations
Tool | Description |
| Simple text search with context |
| Advanced search using Dataview DQL or JsonLogic |
Prerequisites
Obsidian with the Local REST API plugin installed and enabled
Node.js v18 or higher
API Key from Obsidian's Local REST API settings
Quick Start
npm install
npm run build
npm run setupThe interactive setup wizard will guide you through:
Entering your Obsidian API Key
Selecting transport mode (stdio for Claude Desktop, HTTP for Open WebUI)
Configuring optional settings
After setup, start the server:
# For Open WebUI (HTTP mode)
npm run start:http
# For Claude Desktop (stdio mode)
npm startInstallation
npm install
npm run buildConfiguration
Setup Wizard (Recommended)
Run the interactive setup wizard:
npm run setupThis creates a .env file with your configuration.
Manual Configuration
Alternatively, copy .env.example to .env and edit manually:
cp .env.example .envEnvironment Variables
Variable | Description | Default |
| Obsidian REST API URL |
|
| API Key | (required) |
|
|
|
| Port for HTTP mode |
|
| Enable debug logging |
|
Usage with MCP Clients
Claude Desktop (stdio mode)
Add to your Claude Desktop configuration (claude_desktop_config.json):
{
"mcpServers": {
"obsidian": {
"command": "node",
"args": ["/path/to/Obsidian_MCP/dist/index.js"],
"env": {
"OBSIDIAN_API_URL": "http://127.0.0.1:27123",
"OBSIDIAN_API_KEY": "your-api-key-here"
}
}
}
}Open WebUI (HTTP mode)
Start the server in HTTP mode:
npm run start:httpIn Open WebUI, go to Admin Settings → Tools → MCP Servers
Add a new MCP server:
Type: MCP Streamable HTTP
URL:
http://localhost:3000/mcpAuth: None (the server handles Obsidian auth internally)
Click Save
Startup Health Check
When the server starts, it automatically verifies the connection to Obsidian:
========================================
Obsidian MCP Server - Startup Check
========================================
API URL: http://127.0.0.1:27123
Debug Mode: disabled
Checking connection to Obsidian REST API...
✓ Connected to Obsidian REST API
✓ Authenticated successfully
Plugin Version: 3.4.2
Obsidian Version: 1.11.7If there are connection issues, troubleshooting steps are displayed.
Debug Mode
Enable debug logging for verbose output:
DEBUG=true npm startShows detailed logs for API requests, tool calls, and HTTP connections.
Troubleshooting
Open WebUI Connection Failed
Verify server is running:
curl http://localhost:3000/healthCheck configuration:
URL:
http://localhost:3000/mcpAuth: None (not Bearer)
Type: MCP Streamable HTTP
Test the endpoint: The
/mcpendpoint accepts POST requests with MCP protocol messages.
General Issues
Ensure Obsidian is running with Local REST API plugin enabled
Verify API key is correct
Try
DEBUG=true npm startfor detailed logsRe-run setup:
npm run setup
Tool Details
vault_get_file
Get file content with optional format:
markdown(default): Raw markdown contentjson: Parsed note with metadatadocument-map: Shows headings, blocks, frontmatter fields
vault_patch_file
Partial updates without rewriting entire file:
Operations:
append,prepend,replaceTargets: headings, block references, frontmatter fields
search_advanced
Dataview DQL:
TABLE FROM #tag WHERE field = valueJsonLogic:
{"in": ["myTag", {"var": "tags"}]}
Development
# Build
npm run build
# Development with auto-rebuild
npm run dev # stdio mode
npm run dev:http # HTTP mode
# Setup wizard
npm run setup
# Clean build artifacts
npm run cleanLicense
MIT
Available Tools
8 toolssearch_advancedA
Perform an advanced search using Dataview DQL or JsonLogic. Dataview is best for querying metadata and frontmatter (e.g., "TABLE FROM #tag"). JsonLogic is best for complex logical queries on note properties.
Inputs: no named parameters.
search_simpleA
Perform a simple text search across all files in the vault. Returns matching files with context around each match. Best for straightforward text searches.
Inputs: no named parameters.
vault_append_to_fileA
Append content to the end of an existing file. If the file doesn't exist, it will be created. Use this to add content without replacing existing content.
Inputs: no named parameters.
vault_create_fileA
Create a new file in the vault or completely replace an existing file's content. Use this when you want to write the entire file content at once.
Inputs: no named parameters.
vault_delete_fileA
Delete a file from the Obsidian vault. This operation cannot be undone.
Inputs: no named parameters.
vault_get_fileA
Get the content of a file from the Obsidian vault. Can return raw markdown, parsed JSON with metadata (tags, frontmatter, stats), or a document map showing headings, blocks, and frontmatter fields.
Inputs: no named parameters.
vault_listA
List files and directories in the Obsidian vault. Returns a formatted list showing directories (ending with /) and files. Use this to explore the vault structure.
Inputs: no named parameters.
vault_patch_fileA
Partially update a file by inserting content relative to a heading, block reference, or frontmatter field. Operations: append (after target), prepend (before target), or replace. Useful for updating specific sections without rewriting the entire file.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Every tool has a clearly distinct purpose with no ambiguity. The two search tools are well-differentiated (advanced vs. simple), and the file operation tools each handle specific actions (create, get, append, patch, delete, list) without overlap. Descriptions clearly indicate when to use each tool.
All tools follow a consistent verb_noun pattern with snake_case throughout. The 'vault_' prefix groups related file operations, while 'search_' prefixes distinguish query tools, creating a predictable and readable naming convention across all 8 tools.
8 tools is well-scoped for an Obsidian vault management server. This provides complete coverage for core operations (search, file CRUD, vault exploration) without being overwhelming. Each tool earns its place with clear utility for the domain.
The toolset provides complete coverage for Obsidian vault operations. It includes search capabilities (simple and advanced), full file lifecycle management (create, get, append, patch, delete), and vault exploration (list). No obvious gaps exist for the stated purpose of managing an Obsidian vault.
Related MCP Connectors
Search your Obsidian vault to quickly find notes by title or keyword, summarize related content, a…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
Connect AI assistants to your GitHub-hosted Obsidian vault to seamlessly access, search, and analy…