MCP ExplorerExplorer

MCP server for Obsidian

@MarkusPfundsteinon a month ago
1062 MIT
FreeCommunity
Knowledge Base
#obsidian#note-taking#knowledge-management#rest-api#mcp
MCP server to interact with Obsidian via the Local REST API community plugin.

Overview

What is MCP server for Obsidian

The MCP server for Obsidian is a tool that allows users to interact with their Obsidian vault through a Local REST API provided by a community plugin. It facilitates the management of files and content within Obsidian via structured API commands.

Use cases

Users can utilize the MCP server for tasks such as listing files, retrieving content from specific notes, searching across their vault, appending or patching content within notes, and deleting files or directories. Specific examples include summarizing meeting notes, searching for references to tools like Azure CosmosDb, and content management.

How to use

To use the MCP server, users must have the Obsidian REST API community plugin installed and activated in their Obsidian settings. They then need to configure the MCP server with their API key and host, either by updating server configuration files or creating a .env file. Users can prompt Claude with commands that leverage the various tools available in the server.

Key features

Key features of the MCP server include the ability to list files and directories, fetch file contents, perform searches across the vault, and modify notes through content insertion or appending. It simplifies content management tasks within Obsidian, enhancing the user experience.

Where to use

The MCP server is intended for use within the Obsidian application environment, particularly on local setups where users maintain their vaults. It caters to anyone looking to streamline their note-taking and document management processes in Obsidian by leveraging API interactions.

Content

MCP server for Obsidian

MCP server to interact with Obsidian via the Local REST API community plugin.

server for Obsidian MCP server

Components

Tools

The server implements multiple tools to interact with Obsidian:

  • 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: Return the content of a single file in your vault.
  • search: Search for documents matching a specified text query across all files in the vault
  • patch_content: Insert content into an existing note relative to a heading, block reference, or frontmatter field.
  • append_content: Append content to a new or existing file in the vault.
  • delete_file: Delete a file or directory from your vault.

Example prompts

Its good to first instruct Claude to use Obsidian. Then it will always call the tool.

The use prompts like this:

  • Get the contents of the last architecture call note and summarize them
  • 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.

Configuration

Obsidian REST API Key

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

  1. Add to server config (preferred)
{
  "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>"
    }
  }
}
  1. Create a .env file in the working directory with the following required variables:
OBSIDIAN_API_KEY=your_api_key_here
OBSIDIAN_HOST=your_obsidian_host
OBSIDIAN_PORT=your_obsidian_port

Note:

  • You can find the API key in the Obsidian plugin config
  • Default port is 27124 if not specified
  • Default host is 127.0.0.1 if not specified

Quickstart

Install

Obsidian REST API

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

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

Development/Unpublished Servers Configuration
{
  "mcpServers": {
    "mcp-obsidian": {
      "command": "uv",
      "args": [
        "--directory",
        "<dir_to>/mcp-obsidian",
        "run",
        "mcp-obsidian"
      ],
      "env": {
        "OBSIDIAN_API_KEY": "<your_api_key_here>",
        "OBSIDIAN_HOST": "<your_obsidian_host>",
        "OBSIDIAN_PORT": "<your_obsidian_port>"
      }
    }
  }
}
Published Servers Configuration
{
  "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>"
      }
    }
  }
}

Development

Building

To prepare the package for distribution:

  1. Sync dependencies and update 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 run mcp-obsidian

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.log

Tools

obsidian_list_files_in_dir
Lists all files and directories that exist in a specific Obsidian directory.
obsidian_list_files_in_vault
Lists all files and directories in the root directory of your Obsidian vault.
obsidian_get_file_contents
Return the content of a single file in your vault.
obsidian_simple_search
Simple search for documents matching a specified text query across all files in the vault. Use this tool when you want to do a simple text search
obsidian_patch_content
Insert content into an existing note relative to a heading, block reference, or frontmatter field.
obsidian_append_content
Append content to a new or existing file in the vault.
obsidian_delete_file
Delete a file or directory from the vault.
obsidian_complex_search
Complex search for documents using a JsonLogic query. Supports standard JsonLogic operators plus 'glob' and 'regexp' for pattern matching. Results must be non-falsy. Use this tool when you want to do a complex search, e.g. for all documents with certain tags etc.
obsidian_batch_get_file_contents
Return the contents of multiple files in your vault, concatenated with headers.
obsidian_get_periodic_note
Get current periodic note for the specified period.
obsidian_get_recent_periodic_notes
Get most recent periodic notes for the specified period type.
obsidian_get_recent_changes
Get recently modified files in the vault.

Comments

Recommend MCP Servers

View All MCP Servers