Obsidian Vault MCP server

A Model Context Protocol server designed for LLMs to interact with Obsidian vaults. It enables AI assistants to manage knowledge bases through a standardized interface, providing file operations, search capabilities, and property management for Obsidian vaults. The server requires the Local REST API plugin in Obsidian to function.

Installation

Prerequisites

• Node.js installed on your system
• Obsidian with the Local REST API plugin enabled

Option 1: Clone and Build

1. First, enable the Local REST API plugin in your Obsidian application.

2. Clone the repository and build the project:

   git clone [email protected]:cyanheads/obsidian-mcp-server.git
   cd obsidian-mcp-server
   npm install
   npm run build
   

3. Configure the server using environment variables (see Configuration section).

Option 2: Install via npm

1. Enable the Local REST API plugin in Obsidian.

2. Install the package using npm:

   # Install locally (in a project)
   npm install obsidian-mcp-server
   
   # Or install globally
   npm install -g obsidian-mcp-server
   

Configuration

Add the server to your MCP client settings (e.g., claude_desktop_config.json or cline_mcp_settings.json):

{
  "mcpServers": {
    "obsidian-mcp-server": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your_api_key_here",
        "VERIFY_SSL": "false",
        "OBSIDIAN_PROTOCOL": "https",
        "OBSIDIAN_HOST": "127.0.0.1",
        "OBSIDIAN_PORT": "27124",
        "REQUEST_TIMEOUT": "5000",
        "MAX_CONTENT_LENGTH": "52428800",
        "MAX_BODY_LENGTH": "52428800",
        "RATE_LIMIT_WINDOW_MS": "900000",
        "RATE_LIMIT_MAX_REQUESTS": "200",
        "TOOL_TIMEOUT_MS": "60000"
      }
    }
  }
}

Environment Variables

• OBSIDIAN_API_KEY (Required): Your API key from Obsidian's Local REST API plugin settings
• VERIFY_SSL (Default: false): Enable SSL verification
• OBSIDIAN_PROTOCOL (Default: "https"): Protocol (http or https)
• OBSIDIAN_HOST (Default: "127.0.0.1"): Host address
• OBSIDIAN_PORT (Default: 27124): Port number
• REQUEST_TIMEOUT (Default: 5000): Request timeout in milliseconds
• MAX_CONTENT_LENGTH (Default: 52428800 [50MB]): Max response content length
• MAX_BODY_LENGTH (Default: 52428800 [50MB]): Max request body length
• RATE_LIMIT_WINDOW_MS (Default: 900000 [15 min]): Rate limit window
• RATE_LIMIT_MAX_REQUESTS (Default: 200): Max requests per window
• TOOL_TIMEOUT_MS (Default: 60000 [1 min]): Tool execution timeout

Available Tools

File Operations

• obsidian_list_files_in_vault Lists all files and directories within the root of your Obsidian vault. Parameters: None

• obsidian_list_files_in_dir Lists files and directories within a specific folder in your vault. Parameters: dirpath* (Path to list files from, relative to vault root)

• obsidian_get_file_contents Retrieves the full content of a specified file within your vault. Parameters: filepath* (Path to the file, relative to vault root)

• obsidian_append_content Appends content to the end of a specified file. Parameters:

  • filepath*: Path to the file
  • content*: Content to append

• obsidian_update_content Overwrites the entire content of a specified file. Parameters:

  • filepath*: Path to the file
  • content*: The new content

Search Operations

• obsidian_find_in_file Performs full-text search across vault files. Parameters:

  • query*: Text pattern to search for
  • contextLength: Characters of context around matches (default: 10)

• obsidian_complex_search Finds files based on path patterns using JsonLogic queries. Parameters: query* (A JsonLogic query object targeting file paths)

• obsidian_get_tags Retrieves all tags defined in YAML frontmatter of markdown files. Parameters: path (Optional folder path to restrict the search)

Property Management

• obsidian_get_properties Retrieves properties from the YAML frontmatter of a specified note. Parameters: filepath* (Path to the note file)

• obsidian_update_properties Updates properties within the YAML frontmatter of a specified note. Parameters:

  • filepath*: Path to the note file
  • properties*: Properties to update
  • replace: If true, array properties will be replaced instead of merged (default: false)

Resources

• obsidian://tags - Lists all tags used across the Obsidian vault with their usage counts

How to add this MCP server to Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > MCP and click "Add new global MCP server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.