obsidian-mcp
Single-container MCP server for an Obsidian vault. Handles authentication, CORS, SSE streaming, and exposes 14 vault-management tools — no nginx or supergateway needed.
Quick start
docker run -d --name mcp \
-p 127.0.0.1:3000:3000 \
-v /path/to/your/vault:/vault \
-e VAULT_PATH=/vault/Obsidian\ Vault \
ghcr.io/lpfchan/mcp
Or with docker-compose:
services:
mcp:
build: .
container_name: mcp
ports:
- 127.0.0.1:3000:3000
environment:
- VAULT_PATH=/vault/Obsidian Vault
volumes:
- ./vault:/vault
Configuration
| Variable | Default | Description |
|---|---|---|
VAULT_PATH | (required) | Path to the Obsidian vault inside the container |
MCP_TOKEN | f304...fcb | API token for Bearer or URL-path auth |
PORT | 3000 | HTTP listen port |
ALLOWED_ORIGIN | https://chat.lost.plus | CORS allowed origin |
HOST | 0.0.0.0 | Bind address |
Authentication supports both Authorization: Bearer <token> headers and URL-path tokens (/<token>/mcp).
Tools
| Tool | Description |
|---|---|
list-available-vaults | Lists available vault names |
read-note | Reads a note's content |
create-note | Creates a new note |
edit-note | Edits a note (append, prepend, overwrite, or targeted replace) |
search-vault | Searches content, filenames, or tags (with fuzzy mode) |
list-notes | Lists all .md files with optional stats |
move-note | Moves or renames a note |
create-directory | Creates a directory in the vault |
delete-note | Moves a note to .trash |
add-tags | Adds tags to frontmatter |
remove-tags | Removes tags from frontmatter |
rename-tag | Renames a tag across all notes |
delete-directory | Permanently deletes a directory |
open-trash | Lists files in .trash |
recover-from-trash | Recovers a file from .trash |
Testing
npm install
npm test
59 tests across 18 suites covering every tool, auth, CORS, and edge cases.