obsidian-ai-miniserver 0.3.1

Expose your Obsidian vault via REST API and streamable HTTP MCP server for AI tool access

obsidian-ai-miniserver

A complete Obsidian tool in ~1,776 tokens!

Makes your Obsidian vault accessible via REST API (OpenAPI) and a streamable HTTP MCP server. Enables AI to find, read, and edit text notes. Supports multiple users with token-based auth and path-level access control.

Browse the API on Redocly or Swagger.

What's good about it

Access anywhere

• WebUI for human to manage
• MCP http streaming for agents to use
• OpenAPI api for agents and web-app integrations

Control Access

• Create multiple users with their own keys, different read/write permissions and folder access
• Keep your personal vault, personal — while enabling agents access to specific subsets

Highly Flexible

• Works for any form of text files in vault, json, etc
• AI can do advanced regex searches

Run anywhere

• Locally on PC w/ Obsidian app
• Headless in container — With ob sync or just from folder

Ruthless minimalism

• Single CLI command
• Single tool interface for AI
• AI able to perform all admin work, once AI connects it can take over setup for you

Maximum Token Efficiency = Faster and Cheaper

• Maximally powerful requests to minimize request and param counts
• The entire tool schema uses ~1,776 tokens thanks to minimized docstrings, zero duplication or boilerplate
• Batch request enables multiple LLM actions in one iteration, massively improving token efficiency
• Limits, Paging, Sort on all requests, AI can adjust snippet sizes on search results, etc — no more tokens than it needs

Quick start

pip install obsidian-ai-miniserver
obs_ai_ms start /path/to/vault --admin-token your_token

This starts both servers on their default ports. Connect your AI to the MCP endpoint or the REST API.

Options

Option	Env Var	Default	Description
vault_path	—	(required)	Path to the Obsidian vault
--admin-token	OBS_AI_MS_ADMIN_TOKEN	(none)	Auth token for the admin user
--port	OBS_AI_MS_PORT	8747	Server port
--host	OBS_AI_MS_HOST	127.0.0.1	Host to bind to. Use 0.0.0.0 to allow remote access
--fqdn	OBS_AI_MS_FQDN	(none)	Public URL for self-linking
--base-path	OBS_AI_MS_BASE_PATH	(none)	Base path when behind a reverse proxy

Persistence

Config is stored at .obsidian/obsidian_ai_miniserver.json inside the vault — user list with tokens and path access rules.

Headless deployment

Run headless in a Docker container with Obsidian Headless — no desktop app needed. The docker-compose.yaml is fully self-contained: it installs everything from the internet at startup.

You can paste it directly into a container platform like Coolify — just set the environment variables:

Env Var	Description
OBSIDIAN_USERNAME	Your Obsidian account email
OBSIDIAN_PASSWORD	Your Obsidian account password
OBSIDIAN_VAULTNAME	Name of your remote vault
OBS_AI_MS_ADMIN_TOKEN	Admin auth token
OBS_AI_MS_HOST	Host to bind to (default 0.0.0.0)
OBS_AI_MS_PORT	Server port (default 8747)
OBS_AI_MS_FQDN	Public URL for self-linking
OBS_AI_MS_BASE_PATH	Base path when behind a reverse proxy

Or via CLI:

OBSIDIAN_USERNAME=[e-mail] OBSIDIAN_PASSWORD=secret OBSIDIAN_VAULTNAME="My Vault" docker compose up

API reference

All requests go to POST /api/obsidian with a kind field that discriminates the request type. Available kinds:

• get_vault_info — vault name, daily notes folder, your user info
• list_files — list files and folders at a path
• read_text — read a note's text
• write_text — overwrite a note
• append_text — append to a note
• replace_text — find and replace text in a note
• move_file — move, copy, or delete a file
• search_files — regex search across notes and text files with context snippets
• batch — send multiple requests in one call
• list_users / upsert_user — admin user management