Obsidian MCP Server

TypeScript MCP server for Obsidian with core vault operations, graph analytics, and semantic search.

Features

Core Tools: Read, write, search, append, delete files in your Obsidian vault
Periodic Notes: Access daily, weekly, monthly notes and recent changes
Advanced Search: JsonLogic queries for complex filtering
Graph Tools: Orphan detection, centrality analysis, cluster detection, path finding
Semantic Search: Smart Connections integration for concept-based search

Prerequisites

Node.js 18+
Obsidian with Local REST API plugin installed and enabled
(Optional) Dataview plugin for get_recent_changes
(Optional) Periodic Notes plugin for periodic note tools
(Optional) Smart Connections plugin for semantic search

Installation

From npm

npm install -g @connorbritain/obsidian-mcp-server

From source

git clone https://github.com/ConnorBritain/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install
npm run build

Configuration

Set the following environment variables:

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OBSIDIAN_API_KEY | Yes | - | API key from Local REST API plugin settings | | OBSIDIAN_HOST | No | 127.0.0.1 | Obsidian REST API host | | OBSIDIAN_PORT | No | 27124 | Obsidian REST API port | | OBSIDIAN_PROTOCOL | No | https | http or https | | OBSIDIAN_VAULT_PATH | No | - | Path to vault (required for graph tools) | | SMART_CONNECTIONS_PORT | No | - | Port for Smart Connections API | | GRAPH_CACHE_TTL | No | 300 | Graph cache TTL in seconds |

MCP Client Configuration

Using npx (Recommended)

Use npx for the simplest setup:

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@connorbritain/obsidian-mcp-server"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Using Local Build (Development)

If running from source:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
      }
    }
  }
}

Config File Locations

| Client | Config Path | |--------|-------------| | Claude Desktop (Windows) | %APPDATA%\Claude\claude_desktop_config.json | | Claude Desktop (Mac/Linux) | ~/.config/claude/claude_desktop_config.json | | Windsurf | ~/.windsurf/mcp_config.json | | Cursor | ~/.cursor/mcp_config.json |

Available Tools

Core File Operations

| Tool | Description | |------|-------------| | list_files_in_vault | List all files/directories in vault root | | list_files_in_dir | List files in a specific directory | | get_file_contents | Read a single file | | batch_get_file_contents | Read multiple files concatenated with headers | | delete_file | Delete file or directory |

Write Operations

| Tool | Description | |------|-------------| | append_content | Append to file (creates if missing) | | put_content | Overwrite file content | | ~~patch_content~~ | ⚠️ Disabled: Insert content relative to heading/block (awaiting Obsidian REST API fix - see issue #146) |

Note: The patch_content tool is currently disabled due to known bugs in the Obsidian Local REST API plugin. Use the read-modify-write pattern with get_file_contents + put_content as a reliable alternative.

Search

| Tool | Description | |------|-------------| | search | Keyword search across vault | | complex_search | JsonLogic query search (glob, regexp support) | | pattern_search | Regex pattern extraction with context (requires vault path) |

Periodic Notes & Recent Changes

| Tool | Description | |------|-------------| | get_periodic_note | Get current daily/weekly/monthly/quarterly/yearly note | | get_recent_periodic_notes | Get recent periodic notes with optional content | | get_recent_changes | Get recently modified files (requires Dataview) |

Obsidian Integration

| Tool | Description | |------|-------------| | get_active_file | Get the currently active file in Obsidian | | open_file | Open a file in Obsidian | | list_commands | List all available Obsidian commands | | execute_command | Execute one or more Obsidian commands |

Graph Tools (requires OBSIDIAN_VAULT_PATH)

| Tool | Description | |------|-------------| | get_vault_stats | Overview stats (notes, links, orphans, clusters) | | find_orphan_notes | Notes with no incoming/outgoing links | | get_note_connections | Incoming/outgoing links + tags for a note | | find_path_between_notes | Shortest link path between two notes | | get_most_connected_notes | Top notes by link count or PageRank | | detect_note_clusters | Community detection via graph analysis | | get_vault_structure | Folder tree structure of vault |

Semantic Tools (requires Smart Connections plugin)

| Tool | Description | |------|-------------| | semantic_search | Conceptual search via Smart Connections | | find_similar_notes | Find semantically similar notes

Development

# Watch mode
npm run dev

# Type check
npm run typecheck

# Build
npm run build

License

MIT

MCP Servers