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

1. Obsidian with Local REST API plugin installed and configured
2. Python 3.10+
3. 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

1. Install the "Local REST API" plugin in Obsidian
2. Enable the plugin in Settings → Community plugins
3. Go to plugin settings and copy your API key
4. 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 file
• append: Add to end
• prepend: 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

1. Search for existing related notes:

   Use obsidian_simple_search with query "systems thinking"
   

2. Read related notes:

   Use obsidian_batch_get_file_contents with discovered notes
   

3. 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

1. Find notes in topic cluster:

   Use obsidian_simple_search or obsidian_get_notes_info
   

2. 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

1. Check current tags:

   Use obsidian_manage_tags with action: "list"
   

2. Add topic tags:

   Use obsidian_manage_tags with action: "add"
   

Best Practices

For Zettelkasten

• Always search first: Use obsidian_simple_search before creating new notes to avoid duplicates
• Atomic notes: One idea per note, clearly titled
• Link liberally: Use obsidian_patch_content to add connections
• Tag consistently: Use obsidian_manage_tags for 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:

1. Verify Obsidian is running
2. Check Local REST API plugin is enabled
3. Verify API key is correct
4. Check port matches plugin settings (default: 27124)

Authentication Errors

Error: "Authentication failed"

Solutions:

1. Check OBSIDIAN_API_KEY environment variable
2. Regenerate API key in plugin settings
3. Ensure no extra spaces in API key

File Not Found

Error: "Resource not found"

Solutions:

1. Verify file path is relative to vault root
2. Check file exists: use obsidian_list_files_in_dir
3. 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

1. Define Pydantic input model
2. Add tool function with @mcp.tool decorator
3. Include proper annotations (readOnlyHint, etc.)
4. Add comprehensive docstring
5. Implement error handling

Contributing

Contributions welcome! Please:

1. Follow existing code style
2. Add Pydantic models for validation
3. Include docstrings with examples
4. 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:

1. Check Troubleshooting section
2. Verify Obsidian Local REST API is working
3. Test with simple tools first (list_files_in_vault)
4. Open an issue with error messages and configuration

---

Happy note-taking! 📝✨