MCP Vault Server

MCP server that interacts with an Obsidian Vault directly on the filesystem (or indirectly via the REST API community plugin)

python

1

GitHub Stars

python

Language

6 months ago

First Indexed

2 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
  "mcpServers": {
    "phate45-mcp-vault": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/home/user/Projects/mcp-vault",
        "mcp-vault"
      ],
      "env": {
        "VAULT_PATH": "YOUR_VAULT_PATH"
      }
    }
  }
}

You run a local MCP server named mcp-vault to let AI assistants interact with your Obsidian vault. It exposes actions like moving or renaming files, extracting markdown headings, and resolving heading hierarchies so your vault structure stays consistent as you work with AI-powered workflows.

How to use

You connect to the MCP server from an MCP client by configuring a server entry that uses the stdio transport. This enables you to issue tools like moving files, listing headings, and resolving heading chains directly through your AI assistant. The server communicates with Obsidian via the Local REST API plugin and reads markdown files to analyze headings.

Typical workflows you can perform include moving or renaming files inside your vault, quickly extracting all headings from a file to understand its structure, and obtaining the full parent chain for a specific heading so you can reference it unambiguously in your prompts or patches.

How to install

Prerequisites you need before installing the MCP server:

Python >= 3.13
uv for dependency management
Obsidian with the Local REST API plugin installed and configured
The Local REST API plugin running on localhost:27124

Step 1: Set up the project directory and install dependencies.

# Clone the repository
git clone https://github.com/phate45/mcp-vault
cd mcp-vault

# Install dependencies
uv sync

Step 2: Start the server locally for development or testing.

# Run the server (example uses a vault path via environment variable)
VAULT_PATH=<path-to-vault> uv run mcp-vault

Available tools

move_file

Move or rename a file within your vault using the Obsidian Local REST API. Keeps backlinks and vault integrity intact by updating through the Obsidian API.

list_headings

Extract all markdown headings from a file to quickly understand the file's structure without loading the entire content into memory.

nail_heading

Get the full parent chain for a specific heading to create an unambiguous target reference like Parent::Child::Target.