obsidian-mcp

MCP (Model Context Protocol) server that exposes an Obsidian vault as MCP tools. Built on top of obsidian-docker, which runs Obsidian headless with REST API plugins.

Quick Start

# Start Obsidian + MCP server (both keys are required)
OBSIDIAN_API_KEY=your-obsidian-key MCP_API_KEY=your-mcp-key docker compose up -d

# Wait ~60s for Obsidian to boot, then test
curl -s http://localhost:3001/health

The docker-compose.yml pulls the obsidian-docker image automatically.

MCP Tools

Tool	Description
create_note	Create a new note in the vault
read_note	Read the content of a note
update_note	Update (replace) a note's content
delete_note	Delete a note from the vault
list_notes	List all files in the vault
search	Full-text search across the vault
search_dataview	Run a Dataview DQL query
list_commands	List all available Obsidian commands
execute_command	Execute an Obsidian command by ID

These tools are powered by the plugins pre-installed in the obsidian-docker image:

• Local REST API — provides the HTTP endpoints for CRUD, search, and commands
• Omnisearch — full-text search across all content
• Smart Connections — AI-powered semantic search
• Dataview — structured DQL queries over vault metadata

Configuration

Environment Variable	Default	Description
OBSIDIAN_API_KEY	(required)	API key for the Obsidian REST API (must match the key configured in obsidian-docker)
MCP_API_KEY	(required for HTTP)	Bearer token for authenticating MCP clients
OBSIDIAN_API_URL	http://obsidian:27123	URL of the Obsidian REST API
MCP_TRANSPORT	http	Transport mode: http or stdio
MCP_PORT	3001	Port for the HTTP transport

Usage with Claude Desktop

For direct integration with Claude Desktop using stdio transport:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "OBSIDIAN_API_URL": "http://localhost:27123",
        "OBSIDIAN_API_KEY": "your-obsidian-api-key",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

This requires the Obsidian container to be running and accessible at the configured URL. See obsidian-docker for setup.

Development

npm install
npm run build
npm run check  # type-check
npm run lint   # knip (unused code detection)
npm start

Sister Project

obsidian-docker — Headless Obsidian Docker image with REST API plugins. This is the base image that provides the vault and REST API that this MCP server connects to.

License

MIT