Metadata-Version: 2.4
Name: obsidian-mcp-search
Version: 0.1.0
Summary: Self-hosted MCP server exposing embedding-powered semantic search over an Obsidian vault
Project-URL: Homepage, https://github.com/KORThomasJeong/obsidian-mcp-search
Project-URL: Issues, https://github.com/KORThomasJeong/obsidian-mcp-search/issues
License: MIT
License-File: LICENSE
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Indexing
Requires-Python: >=3.11
Requires-Dist: fastembed>=0.3
Requires-Dist: numpy>=1.26
Requires-Dist: pyyaml>=6.0
Requires-Dist: tomli-w>=1.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Provides-Extra: openai
Requires-Dist: openai>=1.0; extra == 'openai'
Provides-Extra: server
Requires-Dist: fastmcp>=0.2; extra == 'server'
Requires-Dist: jinja2>=3.1; extra == 'server'
Requires-Dist: uvicorn>=0.30; extra == 'server'
Requires-Dist: watchdog>=4.0; extra == 'server'
Provides-Extra: sqlite-vec
Requires-Dist: sqlite-vec>=0.1; extra == 'sqlite-vec'
Description-Content-Type: text/markdown

# obsidian-mcp-search

Self-hosted [MCP](https://modelcontextprotocol.io) server that exposes
**embedding-powered semantic search + graph context** over your Obsidian
vault(s). Point it at a folder of `.md` files and it serves hybrid
(BM25 + vector + alias) search to any MCP client — with a web dashboard to
manage vaults and the embedding index.

- No external index: walks a plain Obsidian vault directly
- Local embeddings by default (`intfloat/multilingual-e5-small`, no API key);
  OpenAI/Azure optional
- Returns the matching passage **plus** heading breadcrumb, tags, aliases,
  outbound links and backlinks
- Multiple vaults from one server, each incrementally indexed and watched
- Web admin dashboard at `/admin`

## Install

### pip / uvx

```bash
pip install obsidian-mcp-search
# Or install with the server extra (includes uvicorn + fastmcp):
pip install "obsidian-mcp-search[server]"
obsidian-mcp-search add-vault main /path/to/your/vault
obsidian-mcp-search serve
```

### One-line installer (registers an auto-start service)

```bash
./install.sh --vault /path/to/your/vault
# macOS -> launchd, Linux -> systemd; prints dashboard URL + client config
```

### Docker

```bash
echo "VAULT_PATH=/path/to/your/vault" > .env
docker compose up --build -d
```

## Connect an MCP client

Add to your client config (e.g. Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "obsidian-search": {
      "url": "http://127.0.0.1:8848/mcp"
    }
  }
}
```

Tools exposed: `search(query, k, vault, mode)`, `list_vaults()`,
`read_note(vault, path, section?)`, `reindex(vault)`.

## Dashboard

Open `http://127.0.0.1:8848/admin` to add/remove vaults, reindex, clear an
index, switch the embedding model (re-embeds all vaults), and watch live status.

**Remote dashboard note:** The `/admin` dashboard is intended for **localhost**
use (default: no token, works fully in a browser). Browsers cannot attach
`Authorization: Bearer` headers to page navigations or htmx background requests,
so if you need to access the dashboard remotely you must front the server with a
reverse proxy that handles authentication (e.g. nginx `auth_basic` or an SSO
proxy), or use an SSH tunnel (`ssh -L 8848:127.0.0.1:8848 yourhost`). The
bearer token set via `MCP_AUTH_TOKEN` still fully protects the `/mcp` endpoint
for all MCP clients that send the `Authorization` header correctly.

## Configuration (env vars)

| Var | Default | Meaning |
|---|---|---|
| `OMCS_HOST` | `127.0.0.1` | bind address (set `0.0.0.0` to expose) |
| `OMCS_PORT` | `8848` | port |
| `MCP_AUTH_TOKEN` | _(unset)_ | bearer token; **required** when bound off-localhost |
| `OMCS_EMBED_BACKEND` | `local` | `local` (fastembed) or `openai` |
| `OMCS_EMBED_MODEL` | `intfloat/multilingual-e5-small` | embedding model |
| `OMCS_EMBED_BASE_URL` | _(unset)_ | Azure/OpenAI-compatible base URL |
| `OMCS_PREFER_SQLITE_VEC` | `0` | `1` to use sqlite-vec when loadable |

Indexes live in `~/.cache/obsidian-mcp-search/<vault-hash>/`; the vault registry
in `~/.config/obsidian-mcp-search/config.toml`. Your notes are never written to.

## Security

Binds to localhost by default. To expose remotely, set `MCP_AUTH_TOKEN` and
`OMCS_HOST=0.0.0.0`; the `/mcp` endpoint then requires
`Authorization: Bearer <token>` from all MCP clients. See the Dashboard section
above for notes on remote `/admin` access.

## License

MIT.
