Obsidian MCP Server

How to use

Install and run the MCP server alongside Obsidian. Once running, configure your MCP client to point to the local server port you set up. You can then use the available MCP endpoints to list notes, read content, create or update notes with precise text operations, manage folders, and perform smart searches. The server also supports auto backlink generation and AI-assisted analyses to help you derive strategic insights from your notes.

How to install

Prerequisites: You need Node.js (v16 or higher) and the Obsidian desktop app with the Obsidian Local REST API plugin installed. You will also need to enable and configure the API token and port in the Obsidian plugin.

Choose an installation method that fits your workflow.

One-Click Install (DXT) — Recommended

{ 
  "mcpServers": {
    "obsidian-mcp": {
      "command": "obsidian-mcp",
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_API_TOKEN": "your_api_token",
        "OBSIDIAN_API_PORT": "27123"
      }
    }
  }
}

Remote Install (NPM)

Use the client configuration to run the MCP server via NPX so you don’t have to install globally.

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npx",
      "args": [
        "@huangyihe/obsidian-mcp"
      ],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_API_TOKEN": "your_api_token",
        "OBSIDIAN_API_PORT": "27123"
      }
    }
  }
}

Local Deploy

Choose a local deployment method if you want offline use or full control. You can install globally or run from source, then point your MCP client to the running server.

Option A: Global Install (Recommended)

npm install -g @huangyihe/obsidian-mcp
```

```json
{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "obsidian-mcp",
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_API_TOKEN": "your_api_token",
        "OBSIDIAN_API_PORT": "27123"
      }
    }
  }
}

Option B: Source Deploy

Clone the project, install dependencies, build, and start the server. Then configure your client to connect to the local port.

git clone https://github.com/newtype-01/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build
cp .env.example .env
# edit .env with your configuration
npm start
```

```json
{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "npm",
      "args": ["start"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault",
        "OBSIDIAN_API_TOKEN": "your_api_token",
        "OBSIDIAN_API_PORT": "27123"
      }
    }
  }
}

Option C: Docker Deploy

Use Docker Compose or a Docker run command to deploy the MCP server in a container, with environment variables configured for your vault and API access.

# Configure environment variables in a .env file, then start with Docker Compose
cp .env.example .env
docker-compose up -d
```

```bash
# Or build and run directly
docker build -t obsidian-mcp .
docker run -d \
  --name obsidian-mcp \
  --env-file .env \
  --network host \
  -v /path/to/your/vault:/path/to/your/vault \
  obsidian-mcp

Configuration and security

Configure the vault path, API token, and port in your environment. Keep your API token secure and do not expose it in insecure locations. When using remote installation or shared environments, restrict access to the Obsidian vault and rotate tokens periodically.

Notes on tools and usage patterns

The server provides comprehensive note and folder management, full-text search, and AI-assisted analysis features. Use the available endpoints to list, read, create, update, delete notes, manage folders, and perform batch operations with progress tracking. Take advantage of intelligent search, precision editing, and backlinking to keep your vault well-organized.

list_notes

List notes in the Obsidian vault with optional folder filtering. Includes recursive option to traverse subdirectories.

read_note

Read the content of a specific note in the vault.

read_multiple_notes

Read content from several notes in a single operation for batch processing.

create_note

Create a new note in the vault with full content.

delete_note

Delete a note from the vault.

search_vault

Perform an advanced search across file types with filename and content matching.

move_note

Move or rename notes, including non-text files like PDFs.

manage_folder

Create, rename, move, or delete folders with full hierarchy support.

update_note

Apply text replacements or perform precision insertions (heading-based, block-based) with PATCH-style updates.

auto_backlink_vault

Automatically detect note mentions and convert them to wikilinks with dry-run and batch support.

notes_insight

AI-assisted strategic analysis using structured frameworks, topic discovery, and summarization.