Obsidian Index MCP Server: Semantic Search, Smarter Notes

Supercharge your Obsidian vaults with MCP's semantic search – finally find buried ideas fast, effortlessly. Smarter notes, sharper focus. 🚀" )

Visit Repository

✨ Research And Data

4.4(83 reviews)

124 saves

58 comments

71% of users reported increased productivity after just one week

About Obsidian Index MCP Server

What is Obsidian Index MCP Server: Semantic Search, Smarter Notes?

This MCP server bridges Obsidian note-taking with semantic search capabilities. It indexes your vaults, exposes recent notes as resources via a custom URL scheme, and offers a tool to perform context-aware searches. Think of it as a smart middleman between your Obsidian ecosystem and AI models, making your notes both discoverable and query-able.

How to use Obsidian Index MCP Server: Semantic Search, Smarter Notes?

Follow these steps to get started:

Run the server with: uv run obsidian-index --vault [PATH] --database [PATH] --reindex --watch. The --reindex flag ensures all notes are freshly analyzed, while --watch keeps the index updated as you edit.
Configure your AI client (e.g., Claude Desktop) by editing the claude_desktop_config.json. Use the provided snippets for development or published server setups, replacing placeholder paths with your actual directories.

Obsidian Index MCP Server Features

Key Features of Obsidian Index MCP Server: Semantic Search, Smarter Notes?

Resource Exposure: Notes are served via obsidian:// URLs with markdown type, making them compatible with MCP clients.
Semantic Search Tool: The search-notes tool understands intent behind queries, returning relevant notes even without exact keyword matches.
Real-time Indexing: The --watch flag automatically updates the search index as you modify notes, keeping results current.
Deployment Flexibility: Works seamlessly in both development environments and production setups via configuration tweaks.

Use cases for Obsidian Index MCP Server

Here’s where this tool shines:

Power User Workflows: Automate note retrieval in scripts or AI-driven apps without manual searching.
Contextual Research: Find related ideas or references across projects using natural language queries.
Team Collaboration: Share searchable note indexes between team members via networked servers.
Knowledge Bases: Turn Obsidian vaults into private semantic search engines for personal or enterprise use.

Obsidian Index MCP Server FAQ

FAQ: Troubleshooting & Best Practices

Common questions and solutions:

Why use --reindex every time?: Only needed initially or after major vault changes. Subsequent runs can omit it if --watch is active.
My search results are outdated.: Check --watch is enabled. If edits still don’t update results, try forcing a reindex.
How do I debug connection issues?: Enable verbose logging with DEBUG=obsidian-index* node app.js and review output for API errors. The MCP Inspector tool also helps validate resource endpoints.
Can I use this with other AI platforms?: Yes! The MCP protocol is platform-agnostic. Configure any compatible client (e.g., Perplexity, OpenAI functions) with the exposed endpoints.

Content

Obsidian Index MCP server

An MCP server that provides a semantic search over an Obsidian vault and exposes recent notes as resources.

Components

Resources

The server exposes recently modified notes in your vaults as resources to MCP clients.

Notes are addressed by an obsidian://<VAULT_NAME>/<NOTE_PATH> URL scheme
Notes have the text/markdown media type

Tools

The server implements one tool:

search-notes: Performs semantic search over indexed notes

Run the server

uv run obsidian-index mcp --vault <VAULT_PATH> --database <DATABASE_PATH> --reindex --watch

--vault: Path to the Obsidian vault (can be specified multiple times)
--database: Path to the local database file (will be created if it doesn't exist)
--reindex: Reindex all notes in the vault (you probably want this every time right now)
--watch: Watch for changes in the vault and update the index accordingly

Quickstart

Install

Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

"mcpServers": {
  "obsidian-index": {
    "command": "uv",
    "args": [
      "--directory",
      "<PATH_TO_PROJECT>",
      "run",
      "obsidian-index",
      "--database",
      "<PATH_TO_DATABASE>",
      "--vault",
      "<PATH_TO_VAULT>",
      "--reindex",
      "--watch"
    ]
  }
}

Published Servers Configuration

"mcpServers": {
  "obsidian-index": {
    "command": "uvx",
    "args": [
      "obsidian-index",
      "--database",
      "<PATH_TO_DATABASE>",
      "--vault",
      "<PATH_TO_VAULT>",
      "--reindex",
      "--watch"
    ]
  }
}

Development

Building and Publishing

To prepare the package for distribution:

Sync dependencies and update lockfile:

uv sync

Build package distributions:

uv build

This will create source and wheel distributions in the dist/ directory.

Publish to PyPI:

uv publish

Note: You'll need to set PyPI credentials via environment variables or command flags:

Token: --token or UV_PUBLISH_TOKEN
Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory <PATH_TO_PROJECT> run obsidian-index

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.