Obsidian Local REST API

Interact with your local Obsidian vault using a REST API.

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

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.

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

Purpose: Read content of any file in the vault

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

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

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

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

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

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

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

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

- Node.js 18+ or Bun runtime
- Obsidian Local REST APIrunning locally (default:http://obsidian-local-rest-api.test)

# Clone the repository git clone https://github.com/j-shelfwood/obsidian-local-rest-api-mcp.git cd obsidian-local-rest-api-mcp # Install dependencies with bun bun install # Build the project bun run build

export OBSIDIAN_API_URL="http://obsidian-local-rest-api.test" # Default URL (or http://localhost:8000 for non-Valet setups) export OBSIDIAN_API_KEY="your-api-key" # Optional bearer token

# Development mode with auto-reload bun run dev # Production mode bun run start # Or run directly node build/index.js

{ "mcpServers": { "obsidian-vault": { "command": "npx", "args": ["obsidian-local-rest-api-mcp"], "env": { "OBSIDIAN_API_URL": "http://obsidian-local-rest-api.test", "OBSIDIAN_API_KEY": "your-api-key-if-needed" } } } }

Use the included.vscode/mcp.jsonconfiguration file.

# Watch mode for development bun run dev # Build TypeScript bun run build # Type checking bun run tsc --noEmit

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

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.

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.

If your MCP client shows "Start Failed" or similar errors:

npx obsidian-local-rest-api-mcp --version

# Run our test script node -e " const { spawn } = require('child_process'); const child = spawn('npx', ['obsidian-local-rest-api-mcp'], { stdio: ['pipe', 'pipe', 'pipe'] }); child.stdout.on('data', d => console.log('OUT:', d.toString())); child.stderr.on('data', d => console.log('ERR:', d.toString())); setTimeout(() => { child.stdin.write(JSON.stringify({jsonrpc:'2.0',id:1,method:'initialize',params:{protocolVersion:'2024-11-05',capabilities:{},clientInfo:{name:'test',version:'1.0.0'}}})+'\n'); setTimeout(() => child.kill(), 2000); }, 500); "

- EnsureOBSIDIAN_API_URLpoints to a running Obsidian Local REST API
- Test the API directly:curl http://obsidian-local-rest-api.test/api/files(or your configured API URL)

- Install and runObsidian Local REST API
- Confirm it's accessible on the configured port
- Check if authentication is required

Sync Calendars, Scheduling Links, AI Executive Scheduling Assistant, Unified Calendar