Labsco
j-shelfwood logo

Obsidian Local REST API

★ 8

from j-shelfwood

Interact with your local Obsidian vault using a REST API.

🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#git

Obsidian Local REST API MCP Server

An AI-Native MCP (Model Context Protocol) server that provides intelligent, task-oriented tools for interacting with Obsidian vaults through a local REST API.

🧠 AI-Native Design Philosophy

This MCP server has been redesigned following AI-Native principles rather than simple API-to-tool mapping. Instead of exposing low-level CRUD operations, it provides high-level, task-oriented tools that LLMs can reason about more effectively.

Before vs After: The Transformation

Old Approach (CRUD-Based)New Approach (AI-Native)Why Better
list_files (returns everything)list_directory(path, limit, offset)Prevents context overflow with pagination
create_file + update_filewrite_file(path, content, mode)Single tool handles create/update/append
create_note + update_notecreate_or_update_note(path, content, frontmatter)Intelligent upsert removes decision complexity
search_notes(query)search_vault(query, scope, path_filter)Precise, scopeable search with advanced filtering
(no equivalent)get_daily_note(date)High-level abstraction for common workflow
(no equivalent)get_recent_notes(limit)Task-oriented recent file access
(no equivalent)find_related_notes(path, on)Conceptual relationship discovery

🛠 Available Tools

Directory & File Operations

list_directory

Purpose: List directory contents with pagination to prevent context overflow

{
  "path": "Projects/",
  "recursive": false,
  "limit": 20,
  "offset": 0
}

AI Benefit: LLM can explore vault structure incrementally without overwhelming context

read_file

Purpose: Read content of any file in the vault

{"path": "notes/meeting-notes.md"}

write_file

Purpose: Write file with multiple modes - replaces separate create/update operations

{
  "path": "notes/summary.md",
  "content": "# Meeting Summary\n...",
  "mode": "append"  // "overwrite", "append", "prepend"
}

AI Benefit: Single tool handles all write scenarios, removes ambiguity

delete_item

Purpose: Delete any file or directory

{"path": "old-notes/"}

AI-Native Note Operations

create_or_update_note

Purpose: Intelligent upsert - creates if missing, updates if exists

{
  "path": "daily/2024-12-26",
  "content": "## Tasks\n- Review AI-native MCP design",
  "frontmatter": {"tags": ["daily", "tasks"]}
}

AI Benefit: Eliminates "does this note exist?" decision tree

get_daily_note

Purpose: Smart daily note retrieval with common naming patterns

{"date": "today"}  // or "yesterday", "2024-12-26"

AI Benefit: Abstracts file system details and naming conventions

get_recent_notes

Purpose: Get recently modified notes

{"limit": 5}

AI Benefit: Matches natural "what did I work on recently?" queries

Advanced Search & Discovery

search_vault

Purpose: Multi-scope search with advanced filtering

{
  "query": "machine learning",
  "scope": ["content", "filename", "tags"],
  "path_filter": "research/"
}

AI Benefit: Precise, targeted search reduces noise

Purpose: Discover conceptual relationships between notes

{
  "path": "ai-research.md",
  "on": ["tags", "links"]
}

AI Benefit: Enables relationship-based workflows and serendipitous discovery

Legacy Tools (Backward Compatibility)

The server maintains backward compatibility with existing tools like get_note, list_notes, get_metadata_keys, etc.

Development

# Watch mode for development
bun run dev

# Build TypeScript
bun run build

# Type checking
bun run tsc --noEmit

Architecture

  • ObsidianApiClient - HTTP client wrapper for REST API endpoints
  • ObsidianMcpServer - MCP server implementation with tool handlers
  • Configuration - Environment-based configuration with validation

Error Handling

The server includes comprehensive error handling:

  • API connection failures
  • Invalid tool parameters
  • Network timeouts
  • Authentication errors

Errors are returned as MCP tool call responses with descriptive messages.

Debugging

Enable debug logging by setting environment variables:

export DEBUG=1
export NODE_ENV=development

Server logs are written to stderr to avoid interfering with MCP protocol communication on stdout.