obsidian-mcp-search

Self-hosted MCP 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

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)

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

Docker

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):

{
  "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.

Project links

Data verified by PyPI on Jun 30, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

1 maintainer

PyPI data
Data sourced directly from PyPI's database.
Avatar for TMJ from gravatar.com TMJ

GitHub Statistics

Data verified by PyPI on Jun 30, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

License

MIT License (MIT)

Requires

Python >=3.11

Provides Extra

dev openai server sqlite-vec

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

obsidian_mcp_search-0.1.0.tar.gz (48.1 kB view details)

Uploaded Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

obsidian_mcp_search-0.1.0-py3-none-any.whl (45.4 kB view details)

Uploaded Python 3

File details

Details for the file obsidian_mcp_search-0.1.0.tar.gz.

File metadata

  • Download URL: obsidian_mcp_search-0.1.0.tar.gz
  • Upload date:
  • Size: 48.1 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/6.1.0 CPython/3.13.12

File hashes

Hashes for obsidian_mcp_search-0.1.0.tar.gz
Algorithm Hash digest
SHA256 e1eb9bf2eb25e2f0bd1d66bde7a3d90b5064188c057255cceefb4b528c2d0965
MD5 2da6aff3872c6852ef2baf8497d84211
BLAKE2b-256 c026a4d5237c9a4e3d495430048bf4359e1d42a00812c92d47b632eb2c622608

See more details on using hashes here.

Provenance

The following attestation bundles were made for obsidian_mcp_search-0.1.0.tar.gz:

Publisher: publish.yml on KORThomasJeong/obsidian-mcp-search

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file obsidian_mcp_search-0.1.0-py3-none-any.whl.

File metadata

File hashes

Hashes for obsidian_mcp_search-0.1.0-py3-none-any.whl
Algorithm Hash digest
SHA256 35b7c72fbb13a7fd49f4dc993077cdc5ac4874dd1878cbb2750dcdf81ad3c142
MD5 5ba0b565fc400aaaa3d0e8b53e6354d2
BLAKE2b-256 8028b4ce9d964ae415c83243844b04280232f66f97386476b420e4770438e2f8

See more details on using hashes here.

Provenance

The following attestation bundles were made for obsidian_mcp_search-0.1.0-py3-none-any.whl:

Publisher: publish.yml on KORThomasJeong/obsidian-mcp-search

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page