Metadata-Version: 2.4
Name: obsidian-ai-miniserver
Version: 0.3.0
Summary: Expose your Obsidian vault via REST API and streamable HTTP MCP server for AI tool access
Author-email: William Hogben <will@willhogben.com>
Project-URL: Homepage, https://github.com/whogben/obsidian_ai_miniserver
Project-URL: Repository, https://github.com/whogben/obsidian_ai_miniserver
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastapi
Requires-Dist: fastmcp
Requires-Dist: pydantic
Requires-Dist: typer
Requires-Dist: uvicorn
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Requires-Dist: packaging; extra == "dev"
Requires-Dist: playwright; extra == "dev"
Requires-Dist: twine; extra == "dev"
Requires-Dist: build; extra == "dev"
Dynamic: license-file

# obsidian-ai-miniserver

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.

<img src="https://raw.githubusercontent.com/whogben/obsidian_ai_miniserver/main/docs/images/screenshot_home.png" alt="Home page showing admin user" width="600">

## 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

<img src="https://raw.githubusercontent.com/whogben/obsidian_ai_miniserver/main/docs/images/screenshot_users.png" alt="Users list" width="500">

### 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

<img src="https://raw.githubusercontent.com/whogben/obsidian_ai_miniserver/main/docs/images/screenshot_user.png" alt="User detail with access rules" width="500">

### Less tokens = less cost, faster
- Maximally powerful requests to minimize request and param counts
- Batch request
- Limits, Paging, Sort on all requests, AI can adjust snippet sizes on search results, etc
- Minimized docstrings, zero duplication or boilerplate

## Quick start

```bash
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.

<img src="https://raw.githubusercontent.com/whogben/obsidian_ai_miniserver/main/docs/images/screenshot_login.png" alt="Login page" width="400">

## 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 |

<img src="https://raw.githubusercontent.com/whogben/obsidian_ai_miniserver/main/docs/images/screenshot_config.png" alt="Config page" width="500">

## Persistence

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

<img src="https://raw.githubusercontent.com/whogben/obsidian_ai_miniserver/main/docs/images/screenshot_add_user.png" alt="Add user page" width="500">

## Headless deployment

Run headless in a Docker container with [Obsidian Headless](https://obsidian.md/sync) — no desktop app needed. The [`docker-compose.yaml`](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](https://coolify.io) — 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:

```bash
OBSIDIAN_USERNAME=you@example.com OBSIDIAN_PASSWORD=secret OBSIDIAN_VAULTNAME="My Vault" docker compose up
```

## API reference

See [`openapi.json`](https://github.com/whogben/obsidian_ai_miniserver/blob/main/openapi.json) for full request/response definitions.

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
