mcp-obsidian-via-rest

This MCP server exposes an Obsidian REST API integration to AI assistants via the MCP framework. It provides tools to retrieve note contents and to search Obsidian vaults, including a semantic search capability. The available tools are: get_note_content, which fetches the content and metadata of a given Obsidian note; obsidian_search, which performs a text-based search across notes using a query; and obsidian_semantic_search, which performs a semantic search over notes using a query. To use the server, deploy it (for example via Docker as shown in the configuration), ensure your API_KEY and API_URLS are configured, and then interact with the tools through your MCP client or prompt-driven AI workflow. The multi-URL configuration enables automatic failover and self-healing, selecting the fastest available Obsidian API URL and reconnecting on failure, with transport options including stdio for local use and HTTP JSON-RPC for remote access.

Prerequisites:

• Docker installed and running (or adapt to your preferred environment listed in mcp_config).
• Access to an Obsidian vault via Obsidian REST API (API endpoint(s) reachable from the MCP server).

Installation steps:

1. Pull and run the MCP Obsidian Docker image (as in the example):

# Create a suitable environment file or set env vars directly
export API_KEY=<your_api_key_here>
export API_URLS=["https://127.0.0.1:27124","https://host.docker.internal:27124"]
export DEBUG=mcp:*

# Run via Docker (as shown in the config snippet)
docker run --name mcp-obsidian --rm -i \
  -p 3000:3000 \
  -e API_KEY \
  -e API_URLS \
  -e DEBUG \
  ghcr.io/oleksandrkucherenko/obsidian-mcp:latest

2. If you prefer a different transport, adjust the mcpServers entry to use your chosen method (stdio or http) per the Available transports in the Configure MCP section of the README.
3. Verify the MCP server is up by querying the health or invoking one of the Tools endpoints (get_note_content, obsidian_search, obsidian_semantic_search) via your MCP client.

Prerequisites recap:

• Docker or compatible container runtime
• Access to Obsidian REST API endpoints (API_URLS)
• A valid API_KEY if required by your Obsidian REST setup

Tips and notes:

• Use API_URLS with a JSON array of endpoints for automatic failover; the MCP server will test and select the fastest URL on startup.
• The DEBUG environment variable can help troubleshoot by enabling mcp:* logs.
• Ensure port 3000 (or your configured port) is accessible if you expose the HTTP transport.
• If you rotate API keys, update API_KEY accordingly and restart the container to apply changes.
• For local development, stdio transport may be the simplest option, while HTTP transport is better for remote clients.
• When using multi-URL failover, the server will monitor health every 30 seconds and switch to a healthy URL if the current one becomes unavailable.