Obsidian MCP Server
Provides comprehensive vault operations including file management, content creation and editing, search capabilities, and metadata management through the Obsidian Local REST API plugin. Optimized for Zettelkasten workflows with tools for creating atomic notes, managing tags, updating frontmatter, and maintaining knowledge graphs.
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 create a new note about systems thinking with tags 'philosophy' and 'complexity'"
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.
Custom Obsidian MCP Server
A comprehensive Model Context Protocol (MCP) server for Obsidian vault operations, optimized for Zettelkasten note creation workflows. Works with any LLM that supports MCP (Claude, Perplexity, etc.).
Overview
This MCP server connects to the Obsidian Local REST API plugin and provides 12 powerful tools for:
File Operations: List, read, and manage files in your vault
Content Operations: Create, append, and precisely edit notes
Search: Find related notes across your vault
Metadata Management: Tags, frontmatter, and note properties
Designed specifically for Zettelkasten practitioners who want AI assistance in creating atomic notes, finding connections, and maintaining a knowledge graph.
Related MCP server: Advanced Obsidian MCP Server
Features
✅ Zettelkasten-Optimized: Tools designed for atomic note creation and linking
✅ LLM-Agnostic: Works with any MCP-compatible LLM
✅ Safe by Default: CREATE mode won't overwrite existing notes
✅ Powerful Search: Find existing notes before creating duplicates
✅ Precise Editing: Insert content at specific headings or blocks
✅ Metadata Rich: Full frontmatter and tag management
Prerequisites
Obsidian with Local REST API plugin installed and configured
Python 3.10+
uv (optional but recommended for managing Python environments)
Installation
1. Install the MCP Server
Using uv (recommended):
cd custom-obsidian-mcp
uv syncOr using pip:
cd custom-obsidian-mcp
pip install -e .2. Set Up Obsidian Local REST API
Install the "Local REST API" plugin in Obsidian
Enable the plugin in Settings → Community plugins
Go to plugin settings and copy your API key
Note the port (default: 27124)
3. Configure Environment Variables
Create a .env file or set these variables:
export OBSIDIAN_API_KEY="your-api-key-here"
export OBSIDIAN_HOST="127.0.0.1" # Usually localhost
export OBSIDIAN_PORT="27124" # Default portConfiguration for LLM Clients
Claude Desktop (Desktop App)
Add to your claude_desktop_config.json:
{
"mcpServers": {
"obsidian": {
"command": "/path/to/uvx",
"args": ["custom-obsidian-mcp"],
"env": {
"OBSIDIAN_API_KEY": "your-api-key-here",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}
}
}Or if using pip installation:
{
"mcpServers": {
"obsidian": {
"command": "python",
"args": ["-m", "custom_obsidian_mcp.server"],
"env": {
"OBSIDIAN_API_KEY": "your-api-key-here",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124"
}
}
}
}Perplexity or Other MCP Clients
Use similar configuration structure adapted to your client's format.
Available Tools
File Operations
obsidian_list_files_in_vault
List all files and directories in vault root.
# No parameters neededobsidian_list_files_in_dir
List contents of a specific directory.
{
"dirpath": "Zettelkasten" # Empty string for root
}obsidian_get_file_contents
Read a single file's complete contents.
{
"filepath": "Zettelkasten/202411061234.md"
}obsidian_batch_get_file_contents
Read multiple files at once (max 20).
{
"filepaths": [
"Zettelkasten/note1.md",
"Zettelkasten/note2.md"
]
}Search Operations
obsidian_simple_search
Text search across all vault files with context.
{
"query": "systems thinking",
"context_length": 100 # Optional, default 100
}obsidian_complex_search
Advanced JsonLogic-based search.
{
"query": {"glob": ["*.md", {"var": "path"}]}
}Content Operations
obsidian_write_note
Create or modify notes with optional frontmatter.
{
"filepath": "Zettelkasten/202411061234 Systems Thinking.md",
"content": "# Systems Thinking\n\nContent here...",
"mode": "create", # create|overwrite|append|prepend
"frontmatter": {
"tags": ["zettelkasten", "systems"],
"created": "2024-11-06"
}
}Modes:
create: Only create new files (won't overwrite)overwrite: Replace entire fileappend: Add to endprepend: Add to beginning
obsidian_append_content
Quick append to file (creates if doesn't exist).
{
"filepath": "Zettelkasten/note.md",
"content": "\n## New Section\n\nNew content..."
}obsidian_patch_content
Insert content at specific locations within notes.
{
"filepath": "Zettelkasten/note.md",
"target_type": "heading", # heading|block|frontmatter
"target": "Related Concepts/Subsection",
"operation": "append", # append|prepend|replace
"content": "New related concept..."
}Target Types:
heading: Navigate to heading path (e.g., "Section/Subsection")block: Use block reference (e.g., "^block-id")frontmatter: Update specific frontmatter field
obsidian_delete_file
Delete file or directory (requires confirmation).
{
"filepath": "Zettelkasten/old-note.md",
"confirm": true # Must be true to proceed
}Metadata Operations
obsidian_get_frontmatter
Extract YAML frontmatter from a note.
{
"filepath": "Zettelkasten/note.md"
}obsidian_update_frontmatter
Update frontmatter without modifying content.
{
"filepath": "Zettelkasten/note.md",
"updates": {
"tags": ["zettelkasten", "new-tag"],
"status": "published"
}
}obsidian_manage_tags
Add, remove, or list tags.
{
"filepath": "Zettelkasten/note.md",
"action": "add", # add|remove|list
"tags": ["systems-thinking", "mental-models"]
}obsidian_get_notes_info
Get metadata for multiple notes (max 50).
{
"filepaths": [
"Zettelkasten/note1.md",
"Zettelkasten/note2.md"
]
}Returns: tags, creation date, size, and other metadata.
Zettelkasten Workflow Examples
Creating a New Atomic Note
Search for existing related notes:
Use obsidian_simple_search with query "systems thinking"Read related notes:
Use obsidian_batch_get_file_contents with discovered notesCreate new atomic note:
Use obsidian_write_note: - filepath: "Zettelkasten/202411061234 Systems Thinking Core Concept.md" - content: Your atomic note content - mode: "create" (safe - won't overwrite) - frontmatter: {tags: ["zettelkasten", "systems"], created: "2024-11-06"}
Linking Related Notes
Find notes in topic cluster:
Use obsidian_simple_search or obsidian_get_notes_infoAdd connection to existing note:
Use obsidian_patch_content: - target_type: "heading" - target: "Related Concepts" - operation: "append" - content: "- [[202411061234 Systems Thinking Core Concept]]"
Organizing with Tags
Check current tags:
Use obsidian_manage_tags with action: "list"Add topic tags:
Use obsidian_manage_tags with action: "add"
Best Practices
For Zettelkasten
Always search first: Use
obsidian_simple_searchbefore creating new notes to avoid duplicatesAtomic notes: One idea per note, clearly titled
Link liberally: Use
obsidian_patch_contentto add connectionsTag consistently: Use
obsidian_manage_tagsfor topic organizationUse CREATE mode: Default to
mode="create"to prevent accidental overwrites
For Safety
CREATE mode is default: Won't overwrite existing notes
Confirmation required: Destructive operations need explicit confirmation
Test in dev vault: Try tools in a test vault before using on your main Zettelkasten
Troubleshooting
Connection Errors
Error: "Connection error for GET /vault/"
Solutions:
Verify Obsidian is running
Check Local REST API plugin is enabled
Verify API key is correct
Check port matches plugin settings (default: 27124)
Authentication Errors
Error: "Authentication failed"
Solutions:
Check
OBSIDIAN_API_KEYenvironment variableRegenerate API key in plugin settings
Ensure no extra spaces in API key
File Not Found
Error: "Resource not found"
Solutions:
Verify file path is relative to vault root
Check file exists: use
obsidian_list_files_in_dirEnsure proper file extension (e.g.,
.md)
Architecture
custom-obsidian-mcp/
├── src/
│ └── custom_obsidian_mcp/
│ ├── __init__.py
│ ├── server.py # FastMCP server with all tools
│ └── obsidian_client.py # REST API client
├── pyproject.toml # Project configuration
└── README.mdKey Components
FastMCP: Modern Python MCP framework with Pydantic validation
ObsidianClient: Async HTTP client for REST API communication
Pydantic Models: Type-safe input validation for all tools
Error Handling: Actionable error messages guide correct usage
Development
Running Tests
# Verify Python syntax
python -m py_compile src/custom_obsidian_mcp/server.py
# Test basic import
python -c "from custom_obsidian_mcp.server import mcp; print('OK')"Adding New Tools
Define Pydantic input model
Add tool function with
@mcp.tooldecoratorInclude proper annotations (readOnlyHint, etc.)
Add comprehensive docstring
Implement error handling
Contributing
Contributions welcome! Please:
Follow existing code style
Add Pydantic models for validation
Include docstrings with examples
Test with Obsidian Local REST API
License
MIT License - See LICENSE file for details
Acknowledgments
Built on MCP Python SDK
Inspired by MarkusPfundstein's mcp-obsidian
Support
For issues or questions:
Check Troubleshooting section
Verify Obsidian Local REST API is working
Test with simple tools first (list_files_in_vault)
Open an issue with error messages and configuration
Happy note-taking! 📝✨
Available Tools
13 toolsobsidian_append_contentA
Append content to the end of an existing file or create new file.
Quick way to add content to notes. Useful for adding new thoughts, references,
or connections to existing Zettelkasten notes.
Args:
params (AppendContentInput): Contains:
- filepath (str): Path to file
- content (str): Content to append
Returns:
str: Success message with updated file info
Example:
Add a new related concept to an existing note.
Inputs: params (required). Returns: result
obsidian_batch_get_file_contentsARead-onlyIdempotent
Read multiple files at once, concatenated with headers.
Efficient way to read several related Zettelkasten notes together to understand
connections and context before creating new atomic notes.
Args:
params (BatchGetFilesInput): Contains:
- filepaths (List[str]): List of file paths to read (max 20)
Returns:
str: All file contents concatenated with clear separators
Example:
Reads multiple related notes to understand a concept network.
Inputs: params (required). Returns: result
obsidian_delete_fileADestructiveIdempotent
Delete a file or directory from the vault.
DESTRUCTIVE OPERATION. Requires explicit confirmation. Use carefully when
removing outdated or duplicate notes from your Zettelkasten.
Args:
params (DeleteFileInput): Contains:
- filepath (str): Path to file/directory to delete
- confirm (bool): Must be True to proceed with deletion
Returns:
str: Success or error message
Example:
Delete a duplicate note after merging content into another note.
Inputs: params (required). Returns: result
obsidian_get_file_contentsARead-onlyIdempotent
Read the complete contents of a single file from the vault.
Use this to read existing Zettelkasten notes, understand their structure,
and find connections for creating new atomic notes.
Args:
params (GetFileInput): Contains:
- filepath (str): Path to file relative to vault root
Returns:
str: File contents including frontmatter and body
Example:
For filepath="Zettelkasten/202411061234.md", returns the full note content.
Inputs: params (required). Returns: result
obsidian_get_frontmatterARead-onlyIdempotent
Extract YAML frontmatter metadata from a note.
Read metadata like tags, creation date, and other properties from Zettelkasten
notes without loading the full content.
Args:
params (GetFrontmatterInput): Contains:
- filepath (str): Path to file
Returns:
str: JSON object containing frontmatter fields
Example:
Get tags and metadata from a note to understand its classification.
Inputs: params (required). Returns: result
obsidian_get_notes_infoARead-onlyIdempotent
Get metadata for multiple notes including tags, dates, and sizes.
Efficient way to get overview information about several Zettelkasten notes
without reading full content. Useful for analyzing note collections.
Args:
params (GetNotesInfoInput): Contains:
- filepaths (List[str]): Paths to files (max 50)
Returns:
str: JSON array with metadata for each file
Example:
Get info about all notes in a topic cluster to understand their relationships.
Inputs: params (required). Returns: result
obsidian_list_files_in_dirARead-onlyIdempotent
List files and directories in a specific vault directory.
Use this tool to explore the contents of a specific folder, such as your
Zettelkasten directory or any other organized section of your vault.
Args:
params (ListFilesInput): Contains:
- dirpath (str): Relative path to directory (empty for root)
Returns:
str: Formatted list of directories and files in the specified path
Example:
For dirpath="Zettelkasten", lists all notes in your Zettelkasten folder.
Inputs: params (required). Returns: result
obsidian_list_files_in_vaultARead-onlyIdempotent
List all files and directories in the vault root.
This tool shows the top-level structure of your Obsidian vault, helping you
understand the organization and locate folders for Zettelkasten notes.
Returns:
str: Formatted list of directories and files in the vault root
Example:
Returns a markdown-formatted list showing all top-level folders and files.
Inputs: no named parameters. Returns: result
obsidian_manage_tagsA
Add, remove, or list tags in note frontmatter.
Manage tags for organizing Zettelkasten notes. Essential for maintaining
topic clusters and enabling efficient retrieval of related atomic notes.
Args:
params (ManageTagsInput): Contains:
- filepath (str): Path to note
- action (TagAction): 'add', 'remove', or 'list'
- tags (List[str], optional): Tags to add/remove (not needed for 'list')
Returns:
str: Current tags after operation
Example:
Add tags: action='add', tags=['systems-thinking', 'mental-models']
Remove tag: action='remove', tags=['draft']
List tags: action='list'
Inputs: params (required). Returns: result
obsidian_patch_contentA
Insert content at specific locations within notes using headings, blocks, or frontmatter.
CRITICAL: For heading targets, you MUST provide the FULL HIERARCHICAL PATH.
Args:
params (PatchContentInput): Contains:
- filepath (str): Path to file
- target_type (TargetType): 'heading', 'block', or 'frontmatter'
- target (str): See examples below for correct format
- operation (PatchOperation): 'append', 'prepend', or 'replace'
- content (str): Content to insert
Returns:
str: Success message with patch details
HEADING PATH EXAMPLES (MUST use full path with '/'):
✅ CORRECT:
- target="Introduction" (for top-level # Introduction)
- target="Methods/Data Collection" (for ## Data Collection under # Methods)
- target="Results/Analysis/Statistical Tests" (for ### Statistical Tests under ## Analysis under # Results)
❌ WRONG:
- target="Data Collection" (missing parent "Methods")
- target="Statistical Tests" (missing parents "Results/Analysis")
BLOCK REFERENCE EXAMPLE:
- target_type="block", target="^unique-block-id"
FRONTMATTER EXAMPLE:
- target_type="frontmatter", target="tags"
Note: Always read the file first to see the exact heading structure before patching.
Inputs: params (required). Returns: result
obsidian_searchARead-onlyIdempotent
Search vault using powerful JsonLogic queries.
Essential for Zettelkasten workflow: find notes by patterns, content, tags, or complex criteria.
Uses JsonLogic for flexible and powerful searches across your vault.
Args:
params (SearchInput): Contains:
- query (Dict): JsonLogic query object
Returns:
str: List of matching files
Common Examples:
1. Find all markdown files:
{'glob': ['*.md', {'var': 'path'}]}
2. Search for text in content (case-insensitive):
{'in': ['search term', {'lower': [{'var': 'content'}]}]}
3. Find files by name pattern:
{'glob': ['*zettel*', {'var': 'path'}]}
4. Combine conditions (files with "system" in content):
{'and': [
{'glob': ['*.md', {'var': 'path'}]},
{'in': ['system', {'lower': [{'var': 'content'}]}]}
]}
JsonLogic Documentation: https://jsonlogic.com/
Available variables: 'path' (file path), 'content' (file content), 'stat' (file stats)
Inputs: params (required). Returns: result
obsidian_update_frontmatterA
Update YAML frontmatter metadata without modifying note content.
Add or update metadata fields like tags, status, or custom properties in
Zettelkasten notes while preserving all content.
Args:
params (UpdateFrontmatterInput): Contains:
- filepath (str): Path to file
- updates (Dict): Frontmatter fields to add/update
Returns:
str: Success message with updated frontmatter
Example:
Add tags to existing note: updates={'tags': ['zettelkasten', 'systems-thinking']}
Inputs: params (required). Returns: result
obsidian_write_noteA
Create or modify notes with content and optional frontmatter.
Primary tool for Zettelkasten note creation. Supports multiple modes:
- CREATE: Only creates new notes (safe, won't overwrite)
- OVERWRITE: Replaces entire file
- APPEND: Adds content to end
- PREPEND: Adds content to beginning
Args:
params (WriteNoteInput): Contains:
- filepath (str): Where to write the note
- content (str): Note content
- mode (WriteMode): create/overwrite/append/prepend (default: create)
- frontmatter (Dict, optional): YAML frontmatter metadata
Returns:
str: Success message with note location
Example:
Create atomic note: filepath="Zettelkasten/202411061234 Systems Thinking.md",
content="# Systems Thinking...", frontmatter={'tags': ['zettelkasten', 'concepts']}
Inputs: params (required). Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 13 tools
Each tool has a clearly distinct purpose with no significant overlap. For example, obsidian_append_content adds to the end of files, obsidian_patch_content inserts at specific locations, and obsidian_write_note offers multiple write modes. The tools cover different aspects of file operations (read, write, update, delete, search, metadata management) without ambiguity.
All tools follow a consistent 'obsidian_verb_noun' naming pattern throughout. The verbs are descriptive (e.g., append, batch_get, delete, get, list, manage, patch, search, update, write), and the nouns clearly indicate the target resource (e.g., content, file_contents, frontmatter, tags, note). There are no deviations in style or convention.
With 13 tools, the server is well-scoped for managing an Obsidian vault and Zettelkasten workflow. Each tool serves a specific, necessary function, from basic CRUD operations (read, write, update, delete) to advanced features like search, metadata management, and batch operations. The count is neither too sparse nor bloated for the domain.
The tool set provides comprehensive coverage for Obsidian vault management, including full CRUD for files (create, read, update, delete), metadata handling (frontmatter and tags), directory navigation, search, and specialized operations like patching and batch reads. There are no obvious gaps; agents can perform all essential workflows for note-taking and organization.
Maintenance
Related MCP Connectors
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…
Search, read, and safely update Markdown notes in your connected Phasoric knowledge vaults.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAllows AI models to interact with Obsidian notes through the Local REST API, enabling creation, reading, updating, searching of notes, and Git-based automatic backups.1MIT
- AlicenseAqualityDmaintenanceEmpowers AI agents to deeply understand and interact with Obsidian vaults through the Local REST API, enabling advanced features like vault structure discovery, graph analysis, command execution, and batch file operations.1618MIT
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to interact with Obsidian vaults via the Local REST API plugin for comprehensive note management, file operations, and vault navigation. It supports creating and editing notes, executing Obsidian commands, and performing advanced searches using Dataview queries.100 npm52MIT
- FlicenseAqualityNot gradedmaintenanceIntegrates with the Obsidian Local REST API to enable reading, creating, editing, and searching notes within an Obsidian vault. It supports advanced operations like Dataview queries and partial file updates through both stdio and HTTP transport modes.84,244 npm-