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

🛠 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

`find_related_notes`

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.

Prerequisites

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

Installation

Using npx (Recommended)

npx obsidian-local-rest-api-mcp

From Source

# 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

Configuration

Set environment variables for API connection:

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

Usage

Running the Server

# Development mode with auto-reload
bun run dev

# Production mode
bun run start

# Or run directly
node build/index.js

MCP Client Configuration

Claude Desktop

Add to your `claude_desktop_config.json`:

{
  "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"
      }
    }
  }
}

VS Code with MCP Extension

Use the included `.vscode/mcp.json` configuration file.

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.

Troubleshooting

MCP Server Fails to Start

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

1. Test the server directly:

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

Should output the version number.

2. Test MCP protocol:

# 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);
   "

Should show initialization response.

3. Check Environment Variables:

4. Verify Obsidian Local REST API:

Common Issues

"Command not found": Make sure Node.js/npm is installed and npx is available

"Connection refused": Obsidian Local REST API is not running or wrong URL

Laravel Valet .test domains: If using Laravel Valet, ensure your project directory name matches the .test domain (e.g., `obsidian-local-rest-api.test` for a project in `/obsidian-local-rest-api/`)

"Unauthorized": Check if API key is required and properly configured

"Timeout": Increase timeout in client configuration or check network connectivity

Cherry Studio Configuration

For Cherry Studio, use these exact settings:

• Name: `obsidian-vault` (or any name you prefer)
• Type: `Standard Input/Output (stdio)`
• Command: `npx`
• Arguments: `obsidian-local-rest-api-mcp`
• Environment Variables:
  • `OBSIDIAN_API_URL`: Your API URL (e.g., `http://obsidian-local-rest-api.test` for Laravel Valet)
  • `OBSIDIAN_API_KEY`: Optional API key if authentication is required
• Environment Variables:
  • `OBSIDIAN_API_URL`: `http://obsidian-local-rest-api.test` (or your API URL)
  • `OBSIDIAN_API_KEY`: `your-api-key` (if required)

Contributing

1. Fork the repository

2. Create a feature branch

3. Make changes with proper TypeScript types

4. Test with your Obsidian vault

5. Submit a pull request

License

MIT