obsidian_patch_file

Insert content into existing Obsidian notes relative to headings, block references, or frontmatter fields using append, prepend, or replace operations.

Instructions

Insert content into an existing note relative to a heading, block reference, or frontmatter field.

Input Schema

TableJSON Schema

Name	Required	Description
`filepath`	Yes	Path to the file (relative to vault root)
`operation`	Yes	Operation to perform (append, prepend, or replace)
`target_type`	Yes	Type of target to patch
`target`	Yes	Target identifier (heading path, block reference, or frontmatter field)
`content`	Yes	Content to insert

Implementation Reference

src/mcp_obsidian_advanced/tools.py:220-237 (handler)

The run_tool method of PatchContentToolHandler, which validates input arguments and calls the underlying api.patch_content to perform the patching operation, then returns a success message.

def run_tool(self, args: dict) -> Sequence[TextContent | ImageContent | EmbeddedResource]:
    if not all(k in args for k in ["filepath", "operation", "target_type", "target", "content"]):
        raise RuntimeError("filepath, operation, target_type, target and content arguments required")

    api.patch_content(
        args.get("filepath", ""),
        args.get("operation", ""),
        args.get("target_type", ""),
        args.get("target", ""),
        args.get("content", "")
    )

    return [
        TextContent(
            type="text",
            text=f"Successfully patched content in {args['filepath']}"
        )
    ]

src/mcp_obsidian_advanced/tools.py:185-218 (schema)

The get_tool_description method defining the tool's name, description, and input schema for validation.

def get_tool_description(self):
    return Tool(
        name=self.name,
        description="Insert content into an existing note relative to a heading, block reference, or frontmatter field.",
        inputSchema={
            "type": "object",
            "properties": {
                "filepath": {
                    "type": "string",
                    "description": "Path to the file (relative to vault root)",
                    "format": "path"
                },
                "operation": {
                    "type": "string",
                    "description": "Operation to perform (append, prepend, or replace)",
                    "enum": ["append", "prepend", "replace"]
                },
                "target_type": {
                    "type": "string",
                    "description": "Type of target to patch",
                    "enum": ["heading", "block", "frontmatter"]
                },
                "target": {
                    "type": "string", 
                    "description": "Target identifier (heading path, block reference, or frontmatter field)"
                },
                "content": {
                    "type": "string",
                    "description": "Content to insert"
                }
            },
            "required": ["filepath", "operation", "target_type", "target", "content"]
        }
    )

src/mcp_obsidian_advanced/server.py:26-43 (registration)

TOOL_MAPPING dictionary that maps the tool name TOOL_PATCH_CONTENT ("obsidian_patch_file") to its PatchContentToolHandler class, used for registration.

TOOL_MAPPING = {
    tools.TOOL_LIST_FILES_IN_DIR: tools.ListFilesInDirToolHandler,
    tools.TOOL_SIMPLE_SEARCH: tools.SearchToolHandler,
    tools.TOOL_PATCH_CONTENT: tools.PatchContentToolHandler,
    tools.TOOL_PUT_CONTENT: tools.PutContentToolHandler,
    tools.TOOL_APPEND_CONTENT: tools.AppendContentToolHandler,
    tools.TOOL_DELETE_FILE: tools.DeleteFileToolHandler,
    tools.TOOL_COMPLEX_SEARCH: tools.ComplexSearchToolHandler,
    tools.TOOL_BATCH_GET_FILES: tools.BatchGetFilesToolHandler,
    tools.TOOL_PERIODIC_NOTES: tools.PeriodicNotesToolHandler,
    tools.TOOL_RECENT_PERIODIC_NOTES: tools.RecentPeriodicNotesToolHandler,
    tools.TOOL_RECENT_CHANGES: tools.RecentChangesToolHandler,
    tools.TOOL_UNDERSTAND_VAULT: tools.UnderstandVaultToolHandler,
    tools.TOOL_GET_ACTIVE_NOTE: tools.GetActiveNoteToolHandler,
    tools.TOOL_OPEN_FILES: tools.OpenFilesToolHandler,
    tools.TOOL_LIST_COMMANDS: tools.ListCommandsToolHandler,
    tools.TOOL_EXECUTE_COMMANDS: tools.ExecuteCommandsToolHandler,
}

src/mcp_obsidian_advanced/obsidian.py:277-292 (helper)

The core Obsidian API client method that performs the HTTP PATCH request to patch content in a file relative to a target (heading/block/frontmatter) using specific headers.

def patch_content(self, filepath: str, operation: str, target_type: str, target: str, content: str) -> Any:
    url = f"{self.get_base_url()}/vault/{filepath}"
    
    headers = self._get_headers() | {
        'Content-Type': 'text/markdown',
        'Operation': operation,
        'Target-Type': target_type,
        'Target': urllib.parse.quote(target)
    }
    
    def call_fn():
        response = requests.patch(url, headers=headers, data=content, verify=self.verify_ssl, timeout=self.timeout)
        response.raise_for_status()
        return None

    return self._safe_call(call_fn)

src/mcp_obsidian_advanced/tools.py:23-23 (helper)
Constant defining the tool name "obsidian_patch_file" used throughout the codebase.
```
TOOL_PATCH_CONTENT = "obsidian_patch_file"
```

Advanced Obsidian MCP Server