Obsidian Advanced

You can run an Advanced MCP Server to interact with Obsidian from an AI client. It lets you explore vault structure, analyze note links, execute Obsidian commands, read notes in batch, and open files in new editors—enabling AI agents to understand and navigate your knowledge base more effectively.

How to use

You will run the MCP server locally and connect an MCP client to it. Once connected, you can prompt the AI to inspect your vault, search notes, or perform edits within Obsidian. Typical workflows include expanding sections in the active note, summarizing recent notes into a new document, or explaining contexts where certain topics appear across your vault. The server exposes a suite of tools that the AI can call to read, search, modify, and open notes in Obsidian, all while preserving metadata and link information.

How to install

Prerequisites you need before installing the server: a) Node.js and npm or a compatible runtime, b) access to a terminal, and c) an Obsidian vault with the Local REST API plugin installed and an API key generated.

Step 1: Install the MCP server client via Smithery so Claude Desktop can run it automatically.

npx -y @smithery/cli install @ToKiDoO/mcp-obsidian-advanced --client claude

Configuration and starting the server

You will configure environment variables for Obsidian access and control which tools are exposed. The two runtime configurations are provided for local execution. Use the first to start the published MCP server, and the second for a development/test setup.

{
  "mcpServers": {
    "obsidian_adv": {
      "command": "uvx",
      "args": ["mcp-obsidian-advanced"],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault/",
        "OBSIDIAN_HOST": "<your_obsidian_host>",
        "OBSIDIAN_PORT": "<your_obsidian_port>",
        "INCLUDE_TOOLS": ""
      }
    },
    "obsidian_dev": {
      "command": "uv",
      "args": [
        "--directory",
        "/dir/to/mcp-obsidian-advanced",
        "run",
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault/"
      }
    }
  }
}

Security and best practices

Keep your Obsidian API key secret and restrict access to the MCP server. Use a dedicated vault path for this setup if you want to avoid accidental edits to other vaults. When sharing your setup, exclude actual API keys and replace them with placeholders.

Notes on tools and usage patterns

The server exposes a rich set of tools to interact with Obsidian. You can call these tools from your MCP client to inspect the vault, search notes, or edit content across your vault with context. Examples include listing files, batch retrieving notes, updating or patching content, and opening files in new Obsidian leaves for editing. Use the active note as real-time context when composing prompts, and leverage graph analyses to understand connections between notes.

Examples of tools you can use

• List all files and directories in a vault directory
• Retrieve content and metadata for multiple notes
• Create, update, or append to a note
• Patch a note relative to a heading, block, or frontmatter
• Delete a file or folder
• Simple and complex searches across all vault notes
• Get the currently active note and its metadata
• Access periodic notes for daily/weekly/monthly cycles
• Get recently changed notes and recent periodic notes
• Understand the vault structure and visualize note connections
• Open files in new Obsidian leaves and execute Obsidian commands
• List and execute available Obsidian commands

Troubleshooting and tips

If Claude or another client has trouble locating the runtime, you can use system commands to locate the executable you use to start MCP servers. Check the logs for initialization errors and confirm that the Obsidian REST API plugin is installed and enabled, with a valid API key entered in the plugin settings.

Development notes

This server uses the obsidiantools library to discover vault structure and analyze note connections. You can run the development configuration to test changes locally, using the provided directory and run flags.

Available tools

obsidian_list_files_in_dir

List all files and directories in a specified Obsidian directory.

obsidian_batch_get_files

Return the contents and metadata of one or more notes (.md files) in your vault.

obsidian_put_file

Create a new file in your vault or update the content of an existing one.

obsidian_append_to_file

Append content to a new or existing file in the vault.

obsidian_patch_file

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

obsidian_delete_file

Delete a file or directory from your vault.

obsidian_simple_search

Simple search for documents matching a text query across all vault files.

obsidian_complex_search

Complex search using JsonLogic with glob and regexp pattern support.

obsidian_get_active_note

Get the content and metadata of the currently active note in Obsidian.

obsidian_periodic_notes

Get the current periodic note for a specified period (daily, weekly, monthly, quarterly, yearly).

obsidian_recent_periodic_notes

Get most recent periodic notes for a given period type.

obsidian_recent_changes

Get recently modified files in the vault (requires Dataview plugin).

obsidian_understand_vault

Provide a comprehensive understanding of the vault structure, including directory tree and note graph.

obsidian_open_files

Open one or more files in a new Obsidian leaf.

obsidian_list_commands

List all available Obsidian interface commands.

obsidian_execute_commands

Execute one or more commands in the Obsidian interface.