mcp-obsidian

To use this server with Claude Desktop, you must first install and enable the Obsidian REST API community plugin in Obsidian and copy your API key.

Then, edit your claude_desktop_config.json file located at:

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

Use the following configuration for published servers (using uvx):

{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uvx",
      "args": [
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<YOUR_OBSIDIAN_API_KEY>",
        "OBSIDIAN_HOST": "<your_obsidian_host>",
        "OBSIDIAN_PORT": "<your_obsidian_port>"
      }
    }
  }
}

Note: If Claude fails to detect uvx, use the absolute path found via which uvx.

You must provide your Obsidian REST API credentials using one of the following two methods:

Method 1: Server Configuration (Preferred)

Add the credentials directly to your MCP client configuration (e.g., Claude Desktop config) under the env section.

Method 2: .env File

Create a .env file in the working directory with the following variables:

Required variables:

• OBSIDIAN_API_KEY: Your API key from the Obsidian plugin settings.
• OBSIDIAN_HOST: The host address (defaults to 127.0.0.1 if not specified).
• OBSIDIAN_PORT: The port number (defaults to 27124 if not specified).

{
  "mcp-obsidian": {
    "command": "uvx",
    "args": [
      "mcp-obsidian"
    ],
    "env": {
      "OBSIDIAN_API_KEY": "<your_api_key_here>",
      "OBSIDIAN_HOST": "<your_obsidian_host>",
      "OBSIDIAN_PORT": "<your_obsidian_port>"
    }
  }
}

Because MCP servers communicate over stdio, it is recommended to use the MCP Inspector for debugging. You can launch it using npx by pointing it to your local installation directory:

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

Alternatively, you can monitor the server logs directly via the Claude log file:

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

The mcp-obsidian server provides the following tools to interact with your Obsidian vault via the Local REST API:

• list_files_in_vault: Lists all files and directories in the root directory of your Obsidian vault.
• list_files_in_dir: Lists all files and directories in a specific Obsidian directory.
• get_file_contents: Returns the content of a single file in your vault.
• search: Searches for documents matching a specified text query across all files in the vault.
• patch_content: Inserts content into an existing note relative to a heading, block reference, or frontmatter field.
• append_content: Appends content to a new or existing file in the vault.
• delete_file: Deletes a file or directory from your vault.

Use obsidian_append_content to add text to the end of an existing file or create a new one if it doesn't exist. This does not overwrite existing content.

{
  "name": "obsidian_append_content",
  "description": "Append content to a new or existing file in the vault.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "filepath": {
        "type": "string",
        "description": "Path to the file (relative to vault root)",
        "format": "path"
      },
      "content": {
        "type": "string",
        "description": "Content to append to the file"
      }
    },
    "required": ["filepath", "content"]
  }
}

Use obsidian_list_files_in_dir to list files and directories within a specific path relative to the vault root. Note that empty directories are not returned.

{
  "name": "obsidian_list_files_in_dir",
  "description": "Lists all files and directories that exist in a specific Obsidian directory.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "dirpath": {
        "type": "string",
        "description": "Path to list files from (relative to your vault root). Note that empty directories will not be returned."
      }
    },
    "required": ["dirpath"]
  }
}

Use obsidian_simple_search to find documents matching a text query across the entire vault. You can specify a context_length to control how much surrounding text is returned for each match (defaults to 100).

{
  "name": "obsidian_simple_search",
  "description": "Simple search for documents matching a specified text query across all files in the vault.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "description": "Text to a simple search for in the vault."
      },
      "context_length": {
        "type": "integer",
        "description": "How much context to return around the matching string (default: 100)",
        "default": 100
      }
    },
    "required": ["query"]
  }
}

Use obsidian_complex_search to perform advanced queries using JsonLogic. This supports glob and regexp operators for pattern matching against path and content variables.

Examples:

• Match all markdown files: {"glob": ["*.md", {"var": "path"}]}
• Match markdown files with '1221' in content: {"and": [{"glob": ["*.md", {"var": "path"}]}, {"regexp": ["*.1221.*", {"var": "content"}]}]}

Retrieve the content of a single file or multiple files.

• get_file_contents(filepath: str): Returns the raw text content of the file at filepath.
• get_batch_file_contents(filepaths: list[str]): Returns a single concatenated string containing all file contents. Each file is prefixed with # {filepath} and followed by a separator ---. If a file fails to read, an error message is included in the string instead of crashing.