Obsidian Local REST API MCP server for AI agents

The Obsidian Local REST API MCP Server provides an AI-native interface for interacting with Obsidian vaults through a local REST API, offering task-oriented tools that make it easier for language models to work effectively with your notes and files.

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

Prerequisites

Before using the MCP server, you'll need:

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

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.

Cherry Studio Configuration

For Cherry Studio, use these 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: http://obsidian-local-rest-api.test (or your API URL)
- OBSIDIAN_API_KEY: your-api-key (if required)

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
}

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

`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"]}
}

`get_daily_note`

Purpose: Smart daily note retrieval with common naming patterns

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

`get_recent_notes`

Purpose: Get recently modified notes

{"limit": 5}

Advanced Search & Discovery

`search_vault`

Purpose: Multi-scope search with advanced filtering

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

`find_related_notes`

Purpose: Discover conceptual relationships between notes

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

Troubleshooting

MCP Server Fails to Start

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

Test the server directly:
```
npx obsidian-local-rest-api-mcp --version
```
Should output the version number.

Test MCP protocol:

# Run 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.

Check Environment Variables:
- Ensure OBSIDIAN_API_URL points to a running Obsidian Local REST API
- Test the API directly: curl http://obsidian-local-rest-api.test/api/files
Verify Obsidian Local REST API:
- Install and run Obsidian Local REST API plugin
- Confirm it's accessible on the configured port
- Check if authentication is required

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: Ensure project directory name matches the .test domain
"Unauthorized": Check if API key is required and properly configured
"Timeout": Increase timeout in client configuration or check network connectivity

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.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "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"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

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

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

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

3. Restart Claude Desktop for the changes to take effect