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.
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 sync
Or 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 port
Configuration 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 needed
obsidian_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 notes -
Create 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_info -
Add 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 duplicates - Atomic notes: One idea per note, clearly titled
- Link liberally: Use
obsidian_patch_contentto add connections - Tag consistently: Use
obsidian_manage_tagsfor topic organization - Use 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 variable - Regenerate 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_dir - Ensure 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.md
Key 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.tooldecorator - Include 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
- Uses Obsidian Local REST API
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! 📝✨