Xiaozhi-obsidian-mcp

# Tool List MCP server for agent [Xiaozhi](https://xiaozhi.me) to access personal knowledge base [Obsidian](https://obsidian.md). Allows the agent to search, read, create and edit notes directly through the file system — without running the Obsidian application and without external services. ## How it works ``` Xiaozhi cloud (WebSocket) ↕ wss://api.xiaozhi.me/mcp/?token=... mcp_pipe.py ← stdio ↔ WebSocket adapter ↕ stdin/stdout obsidian_mcp_server.py ← MCP server (8 tools) ↕ os.walk / subprocess(rg) / pathlib ~/vault/ ← Obsidian folder (mounted as Docker volume) ``` Obsidian vault is a regular folder with `.md` files. No Obsidian application is required on the server. ## Requirements - Python 3.9+ - `ripgrep` (optional, speeds up search; Python fallback is used without it) - `rapidfuzz` (optional, adds fuzzy search by file names) ## Quick Start ### Native (Linux / Termux) ```bash git clone https://github.com/YOUR_USERNAME/obsidian-mcp cd obsidian-mcp bash setup.sh ``` The script will create `~/mcp-obsidian/`, set up a virtual environment and (on Linux with systemd) install a user service. After installation, edit `~/mcp-obsidian/.env`: ```env MCP_ENDPOINT=wss://api.xiaozhi.me/mcp/?token=YOUR_TOKEN_HERE VAULT_PATH=/home/user/Documents/ObsidianVault ``` ### Docker ```bash git clone https://github.com/YOUR_USERNAME/obsidian-mcp cd obsidian-mcp docker build -t obsidian-mcp . # Read-only docker run -d \ --name obsidian-mcp \ -e MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=..." \ -v /home/user/MyVault:/vault:ro \ obsidian-mcp # Read-write docker run -d \ --name obsidian-mcp \ -e MCP_ENDPOINT="wss://api.xiaozhi.me/mcp/?token=..." \ -v /home/user/MyVault:/vault:rw \ obsidian-mcp ``` ## Configuration (.env) Copy `.env.example` to `.env` and fill in the values: | Variable | Default | Description | |---|---|---| | `MCP_ENDPOINT` | — | Xiaozhi MCP WebSocket endpoint | | `VAULT_PATH` | — | Absolute path to the vault folder | | `KEEP_BACKUPS` | `false` | Save `.bak` before changing files | | `MAX_FILE_SIZE_KB` | `500` | Skip files larger than N KB | | `MAX_READ_FILES` | `5` | Maximum files per `read_notes` call | | `CONTENT_LIMIT_CHARS` | `8000` | One page reading size (Unicode characters) | | `VAULT_TREE_MAX_DEPTH` | `3` | Traverse depth for `vault_tree` (0 = only root) | > ⚠️ **Never commit `.env`** — it contains a token. Only `.env.example` is stored in the repository. ## Tools (8) | Tool | Purpose | |---|---| | `search_notes` | Search by content and file names (AND logic, fuzzy fallback) | | `read_notes` | Read one or multiple notes with pagination | | `create_note` | Create a new note (with autogenerated frontmatter) | | `append_to_note` | Append text to the end of a note | | `replace_in_note` | Replace the first exact text occurrence | | `overwrite_note` | Overwrite an existing note entirely | | `rewrite_note_block` | Edit by lines (delete + insert) | | `vault_tree` | Vault folder map with `.md` file count | ### Usage Examples ``` # Search notes with two words simultaneously search_notes("docker compose") # Read multiple notes at once read_notes(["DevOps/compose.md", "Projects/home-server.md"]) # Review vault structure vault_tree() # List specific folder contents search_notes("", path_prefix="Inbox/") # Add a record to the end of a note append_to_note("Inbox/ideas.md", "\n## 2026-04-11\n- Try Podman") # Replace text precisely replace_in_note("Projects/plan.md", "deadline: april", "deadline: May 2026") ``` ## Health Check ```bash echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' \ | VAULT_PATH=~/vault python obsidian_mcp_server.py ``` Expect a JSON response with an array of 8 tools. ## Project Structure ``` obsidian-mcp/ ├── obsidian_mcp_server.py # MCP server (main file) ├── mcp_pipe.py # stdio ↔ WebSocket adapter │ # (source: github.com/78/mcp-calculator, MIT License) ├── requirements.txt # Python dependencies ├── Dockerfile # Docker image ├── setup.sh # Installation on Linux / Termux ├── .env.example # Configuration template └── .gitignore ``` ## Target Environments | Environment | Launch Method | |---|---| | Any Linux | `python3` + `venv` + systemd user service | | Docker / Podman | `docker run -v ~/vault:/vault obsidian-mcp` | | Termux (Android) | `pkg install python ripgrep git` + `pip install` | ## License MIT `mcp_pipe.py` is borrowed from [github.com/78/mcp-calculator](https://github.com/78/mcp-calculator) (MIT License).