Skip to main content
Glama

Obsidian Local REST API MCP Server

by j-shelfwood
npmGitHub
JavaScript
MIT License
41
OverviewInspectNewSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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.

Prerequisites

Installation

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:
    • 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 (or your configured API URL)
  4. Verify Obsidian Local REST API:
    • Install and run Obsidian Local REST API
    • 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: 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

Install Server
A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Tools

View all tools

A bridge server that allows LLM tools to interact with an Obsidian vault through a local REST API, enabling file operations, note management, and metadata access through natural language.

  1. 🧠 AI-Native Design Philosophy
    1. Before vs After: The Transformation
  2. 🛠 Available Tools
    1. Directory & File Operations
    2. AI-Native Note Operations
    3. Advanced Search & Discovery
    4. Legacy Tools (Backward Compatibility)
  3. Prerequisites
    1. Installation
      1. Using npx (Recommended)
      2. From Source
    2. Configuration
      1. Usage
        1. Running the Server
        2. MCP Client Configuration
      2. Development
        1. Architecture
          1. Error Handling
            1. Debugging
              1. Troubleshooting
                1. MCP Server Fails to Start
                2. Common Issues
                3. Cherry Studio Configuration
              2. Contributing
                1. License

                  Related Resources

                  Related MCP Servers

                  • Obsidian MCP Server

                    cyanheads
                    -
                    security
                    A
                    license
                    -
                    quality
                    Enables interaction between LLMs and Obsidian vaults through the Model Context Protocol, supporting secure file operations, content management, and advanced search capabilities.
                    Last updated -
                    9
                    434
                    116
                    TypeScript
                    Apache 2.0
                    • Apple
                    • Linux

                  • Obsidian MCP REST Server

                    PublikPrinciple
                    -
                    security
                    A
                    license
                    -
                    quality
                    Provides a standardized interface for AI assistants to interact with Obsidian vaults through a local REST API, enabling reading, writing, searching, and managing notes.
                    Last updated -
                    37
                    TypeScript
                    MIT License

                  • Obsidian MCP Server

                    marcelmarais
                    -
                    security
                    F
                    license
                    -
                    quality
                    A lightweight server that enables AI assistants like Cursor & Claude to read from and write to Obsidian vaults, allowing actions like creating notes, checking existing content, and managing todos through natural language.
                    Last updated -
                    434
                    8
                    TypeScript

                  • MCP Obsidian

                    gregkonush
                    -
                    security
                    A
                    license
                    -
                    quality
                    A server implementation that allows AI assistants to read, create, and manipulate notes in Obsidian vaults through the Model Context Protocol.
                    Last updated -
                    1,530
                    1
                    TypeScript
                    MIT License

                  View all related MCP servers

                  New MCP Servers

                  MCP directory API

                  We provide all the information about MCP servers via our MCP API.

                  curl -X GET 'https://glama.ai/api/mcp/v1/servers/j-shelfwood/obsidian-local-rest-api-mcp'

                  If you have feedback or need assistance with the MCP directory API, please join our Discord server