# Obsidian Vault MCP

HTTP [Model Context Protocol](https://modelcontextprotocol.io) server that gives AI agents controlled access to a local [Obsidian](https://obsidian.md) vault.

Built for agent runtimes (Grok bots, Claude, OpenClaw, custom MCP clients) that need to list, read, search, create, update, rename, and carefully delete markdown notes.

## Features

- Streamable HTTP MCP endpoint (`/mcp`)
- Bearer / API-key auth
- Full-vault mode (`ALLOWLIST=*`) or folder allowlists
- Read tools: `list_notes`, `list_folder`, `read_note`, `search_notes`
- Write tools: `create_note`, `append_note`, `update_note`, `create_folder`, `rename_path`, `delete_path`
- Blocks `.obsidian`, `.git`, dotfiles, `.env`, and key material
- Atomic writes + size limits
- Health endpoint for ops: `/healthz`

## Quick start

```bash
npm install
export VAULT_ROOT="/absolute/path/to/your/vault"
export BEARER_TOKEN="$(openssl rand -hex 32)"
export ALLOWLIST="*"
export WRITE_ALLOWLIST="*"
export MODE="read-write"
export PORT=8790
export BIND=127.0.0.1
export PUBLIC_BASE="http://127.0.0.1:8790"
npm start
```

Health check:

```bash
curl -s http://127.0.0.1:8790/healthz | jq .
```

## Environment variables

| Variable | Required | Default | Description |
|---|---|---|---|
| `VAULT_ROOT` | yes | — | Absolute path to the Obsidian vault |
| `BEARER_TOKEN` | yes | — | Shared secret for MCP clients |
| `ALLOWLIST` | no | sample folders | Comma list of relative folders, or `*` for whole vault |
| `WRITE_ALLOWLIST` | no | same as `ALLOWLIST` | Write scope; `*` = whole vault (still blocks secrets/dotfiles) |
| `MODE` | no | `read-write` | `read-write` or `read-only` |
| `PORT` | no | `8790` | Listen port |
| `BIND` | no | `127.0.0.1` | Bind address |
| `PUBLIC_BASE` | no | `http://127.0.0.1:8790` | Public base URL advertised in metadata |
| `MAX_SEARCH_HITS` | no | `25` | Search result cap |
| `MAX_FILE_BYTES` | no | `400000` | Max note size for reads |
| `MAX_WRITE_BYTES` | no | `350000` | Max note size for writes |

Auth headers accepted:

- `Authorization: Bearer <token>`
- `X-Api-Key: <token>`
- `X-Obsidian-Token: <token>`

## MCP tools

### Read
- `list_notes` — list markdown paths (optional prefix)
- `list_folder` — list files/dirs (`recursive` optional)
- `read_note` — read one note + simple frontmatter
- `search_notes` — case-insensitive substring search

### Write (when `MODE=read-write`)
- `create_note` — create markdown note (`overwrite` optional)
- `append_note` — append to note
- `update_note` — replace full note
- `create_folder` — create folder tree
- `rename_path` — rename/move file or folder
- `delete_path` — delete markdown file or folder (`recursive` for non-empty)

Safety:
- never serves `.obsidian`, `.git`, hidden paths, `.env`, or key files
- write limited to `.md` / `.markdown` / `.txt`
- protected top-level structure anchors cannot be deleted wholesale
- no secrets belong in the vault or this server config committed to git

## Reverse proxy example (nginx)

```nginx
location ^~ /obsidian-mcp/ {
  proxy_pass http://127.0.0.1:8790/;
  proxy_http_version 1.1;
  proxy_set_header Host $host;
  proxy_set_header Authorization $http_authorization;
  proxy_set_header X-Api-Key $http_x_api_key;
  proxy_buffering off;
}
```

Expose only over HTTPS and keep `BIND=127.0.0.1` on the Node process.

## Grok / agent prompt snippet

```text
You have MCP tools for an Obsidian vault via obsidian-vault-mcp.

Rules:
1. First call list_folder path="" to see top-level structure.
2. Read OBSIDIAN-STRUCTURE.md if present before reorganizing.
3. Prefer append_note for changelogs; do not rewrite history casually.
4. Create notes only as .md under clear topic folders.
5. Never store secrets, tokens, private keys, or .env values.
6. Use search_notes before creating near-duplicate docs.
7. Use rename_path to organize; use delete_path only for clearly obsolete drafts.
```

## Security notes

- This server is powerful. Treat `BEARER_TOKEN` like a password.
- Prefer network isolation + reverse proxy auth in production.
- Full-vault write mode is intentional for trusted internal agents; tighten `WRITE_ALLOWLIST` for less-trusted bots.
- Do not commit `.env`, tokens, or real vault contents.

## License

MIT