MCP Obsidian Advanced

🚀 Advanced Obsidian MCP Server

An advanced MCP server that interacts with Obsidian through the Local REST API community plugin. It enables AI agents (such as Claude) to comprehensively understand the structure, links, and content of your vault, going beyond basic read and write operations.

Powered by the obsidiantools library, it offers the following advanced features:

• Discover the vault's tree structure to map your note hierarchy.
• Conduct NetworkX graph analysis of note connections for LLM - friendly insights.
• Execute Obsidian commands directly from AI.
• Read batch files with metadata and link details.
• Access your currently active note for real - time context.
• Open notes/files in new Obsidian leaves for seamless editing.

This setup allows AI agents to collaborate with you, enhancing productivity by efficiently navigating and enriching your knowledge base.

✨ Features

Tools

The server implements multiple tools to interact with Obsidian:

Core File Operations

• obsidian_list_files_in_dir: Lists all files and directories in a specific Obsidian directory.
• obsidian_batch_get_files: Returns the contents and metadata of one or more notes (.md files) in your vault.
• obsidian_put_file: Creates a new file in your vault or updates the content of an existing one.
• obsidian_append_to_file: Appends content to a new or existing file in the vault.
• obsidian_patch_file: Inserts content into an existing note relative to a heading, block reference, or frontmatter field.
• obsidian_delete_file: Deletes a file or directory from your vault.

Search Operations

• obsidian_simple_search: Performs a simple search for documents matching a specified text query across all files in the vault.
• obsidian_complex_search: Conducts a complex search for documents using a JsonLogic query with support for 'glob' and 'regexp' pattern matching.

Note Management

• obsidian_get_active_note: Gets the content and metadata of the currently active note in Obsidian.
• obsidian_periodic_notes: Gets the current periodic note for the specified period (daily, weekly, monthly, quarterly, yearly).
• obsidian_recent_periodic_notes: Gets the most recent periodic notes for the specified period type.
• obsidian_recent_changes: Gets recently modified files in the vault.

  ⚠️ Important Note

  This tool requires the Dataview community plugin to function. Make sure to install the Dataview plugin in your vault.

Vault Analysis

• obsidian_understand_vault: Gets a comprehensive understanding of the vault structure, including the directory tree and NetworkX graph of note connections.
• obsidian_open_files: Opens one or more files in the vault in a new leaf.
• obsidian_list_commands: Lists all available commands you can run in the Obsidian interface.
• obsidian_execute_commands: Executes one or more commands in the Obsidian interface.

Example prompts

It's advisable to first instruct Claude (or any other MCP client) to use Obsidian. Then it will always call the tool. For example:

• "Expand on the Marketing section of the report I'm currently working on in Obsidian"
  • Claude will use obsidian_get_active_note, read it, and then edit the note.
• "Search for all files where Azure CosmosDb is mentioned and quickly explain to me the context in which it is mentioned"
• "Summarize the last meeting notes and put them into a new note 'summary meeting.md'. Add an introduction so that I can send it via email."

📦 Installation

Environment Variables

For this MCP server, there are 2 required environment variables that need to be configured:

• OBSIDIAN_API_KEY: Obtain this by installing the Obsidian REST API plugin and going into settings.
• OBSIDIAN_VAULT_PATH: The absolute path to your vault must be set for tools (e.g., obsidian_understand_vault) to function properly.

Additionally, there are 3 optional environment variables that can be altered:

• OBSIDIAN_HOST: Can be changed in the Obsidian REST API plugin settings. Defaults to 127.0.0.1 as per the plugin's default settings.
• OBSIDIAN_PORT: Can be changed in the Obsidian REST API plugin settings. Defaults to 27124 as per the plugin's default settings.
• INCLUDE_TOOLS: This variable controls which tools are available for use.
  • Write the name of the tool(s) you want to include (names listed above), separated by commas.
  • For example, if you only want the obsidian_understand_vault and obsidian_simple_search tools, you would set INCLUDE_TOOLS="obsidian_understand_vault,obsidian_simple_search" in the .env or in the server config.

There are two ways to configure the environment with the Obsidian REST API Key:

1. Add to server config (PREFERRED):

{
  "mcp-obsidian-advanced": {
    "command": "uvx",
    "args": [
      "mcp-obsidian-advanced"
    ],
    "env": {
      "OBSIDIAN_API_KEY": "%3Cyour_api_key_here%3E",
      "OBSIDIAN_HOST": "<your_obsidian_host>",
      "OBSIDIAN_PORT": "<your_obsidian_port>",
      "OBSIDIAN_VAULT_PATH": "</path/to/your/vault>",
      "INCLUDE_TOOLS": ""
    }
  }
}

💡 Usage Tip

Sometimes Claude has issues detecting the location of uv / uvx. You can use which uvx to find and paste the full path in the above config in such cases.

2. Create a .env file in the working directory with the following variables (only OBSIDIAN_API_KEY and OBSIDIAN_VAULT_PATH are required):

OBSIDIAN_API_KEY=your_api_key_here
OBSIDIAN_HOST=your_obsidian_host
OBSIDIAN_PORT=your_obsidian_port
OBSIDIAN_VAULT_PATH=/path/to/your/vault
INCLUDE_TOOLS=name_of_tool1,name_of_tool2,...

💡 Usage Tip

You can find the API key, Host, and Port in the Obsidian plugin config. The default port is 27124 if not specified, and the default host is 127.0.0.1 if not specified.

Install Dependencies

Obsidian REST API

You need the Obsidian REST API community plugin running: https://github.com/coddingtonbear/obsidian-local-rest-api

• You can install it by going to "Community Plugins" in Obsidian and searching for it. Install and enable it in the settings and copy the API key.

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Published Servers Configuration:

{
  "mcpServers": {
    "mcp-obsidian-advanced": {
      "command": "uvx",
      "args": [
        "mcp-obsidian-advanced"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault/"
      }
    }
  }
}

Development/Unpublished Servers Configuration:

{
  "mcpServers": {
    "mcp-obsidian": {
      "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/"
      }
    }
  }
}

📚 Documentation

Additional Documentation for obsidiantools Library and Obsidian REST API

Additional documentation for the obsidiantools library and Obsidian REST API can be found in the docs directory.

• obsidiantools_in_15_minutes_documentation.md is an ipynb file that demonstrates use cases for obsidiantools.
• obsidian_rest_api_documentation.yaml is a yaml file that demonstrates use cases for the Obsidian REST API.

Building

To prepare the package for distribution:

1. Sync dependencies and update the lockfile:

uv sync

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /path/to/mcp-obsidian-advanced run mcp-obsidian-advanced

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

You can also watch the server logs with this command:

tail -n 20 -f ~/Library/Logs/Claude/mcp-server-mcp-obsidian-advanced.log