obsidian

The Obsidian MCP Server exposes a Model Context Protocol (MCP) interface that lets AI assistants interact with your Obsidian vault. It provides a suite of tools to manage notes, folders, frontmatter and tags, perform full-text searches, navigate backlinks and broken links, and perform batch operations. You can run the server locally via npx, or deploy it with Docker for production. Clients (including Claude Desktop, Cursor, or any MCP-compatible client) connect to the server using the SSE endpoint /sse and issue requests to the available tools such as read-note, create-note, update-frontmatter, or search-vault. A typical workflow is to run the server with VAULT_PATH pointing to your vault, then connect an MCP client to http://localhost:3001/sse to start querying your notes through natural language prompts.

Prerequisites: Node.js v18+ (and npm), optionally Docker for containerized deployment.

Installation (Node/npm, quick start):

1. Ensure Node.js is installed: node --version (should be >= 18).
2. Install dependencies and start via npx (no global install required):
   • For a quick start without installation: VAULT_PATH=/path/to/vault npx -y @smith-and-web/obsidian-mcp-server
   • With a specific port and compact responses: VAULT_PATH=/path/to/vault PORT=3001 COMPACT_RESPONSES=true npx -y @smith-and-web/obsidian-mcp-server
3. Optional local install:
   • npm install
   • Create a start script in package.json if desired, e.g. "start": "node dist/server.js".

Docker (recommended for production):

1. Pull and run the image: docker run -d
   --name obsidian-mcp
   -v /path/to/your/vault:/vault:rw
   -p 3001:3000
   -e VAULT_PATH=/vault
   ghcr.io/smith-and-web/obsidian-mcp-server:latest
2. Verify: curl http://localhost:3001/health

Docker Compose example: version: '3.8' services: obsidian-mcp: image: ghcr.io/smith-and-web/obsidian-mcp-server:latest container_name: obsidian-mcp restart: unless-stopped volumes: - /path/to/your/vault:/vault:rw ports: - "3001:3000" environment: - VAULT_PATH=/vault

Environment variables you may want to set:

• VAULT_PATH: filesystem path to your Obsidian vault (required).
• PORT: the port the MCP server should listen on (default 3000 inside container; you may expose 3001 externally as in examples).
• COMPACT_RESPONSES: enable or disable compacted response mode to reduce payload size. Common endpoints: /health for health checks, /sse for Server-Sent Events stream used by MCP clients. If you run via Docker, ensure the vault path is mounted with read/write access. The server supports a wide range of tools (read-note, create-note, write-note, delete-note, list-vault, get-frontmatter, search-vault, get-backlinks, find-broken-links, find-replace, etc.) and can be consumed by any MCP-compatible client through mcp-remote or direct SSE. If you encounter issues, verify VAULT_PATH correctness, ensure permissions on the vault directory, and confirm the server process can bind to the desired port (adjust PORT or docker port mapping as needed).