Skip to main content
Glama

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

  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

Text search across all vault files with context.

{
  "query": "systems thinking",
  "context_length": 100  # Optional, default 100
}

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"}
  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

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! 📝✨

Available Tools

13 tools
obsidian_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_contentsA
Read-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_fileA
DestructiveIdempotent

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_contentsA
Read-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_frontmatterA
Read-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_infoA
Read-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_dirA
Read-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_vaultA
Read-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_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

    A4.4/5.0

    Scored across 13 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness5/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      D
      maintenance
      Empowers 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.
      16
      18
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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 npm
      52
      MIT
    • F
      license
      A
      quality
      Not graded
      maintenance
      Integrates 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.
      8
      4,244 npm
      -