obsidian

This MCP server provides a Ruby-based interface to interact with your Obsidian vault using the Model Context Protocol. It exposes tools to search notes by content, title, or tags, read full notes including frontmatter and links, list all notes with metadata, and filter notes by tags. It also offers resources for vault statistics and a tag cloud to analyze usage patterns. To start, run the server entry script, and then use an MCP client or the MCP Inspector to issue tool calls like search_notes, read_note, list_notes, and find_by_tags. The server will either auto-discover your vault via the OBSIDIAN_VAULT_PATH environment variable or use the default vault discovery logic described in the README.

Example capabilities you can leverage:

• Search Notes: Find notes by keywords across content, titles, and tags.
• Read Note: Retrieve the full text of a single note including its frontmatter and internal links.
• List Notes: Retrieve a vault-wide list of notes with basic metadata for exploration.
• Find by Tags: Filter notes by one or more tags with flexible matching.
• Vault Statistics: Get metrics such as total notes, word counts, and tag counts.
• Tag Cloud: Analyze tag usage across the vault to identify dominant topics.

Prerequisites:

• Ruby installed (tested with Ruby and Bundler in a typical environment)
• Bundler gem available
• Access to the Obsidian vault you want to expose to MCP

Steps:

1. Clone the repository (or download the release): git clone <repository-url> cd obsidian-mcp-server

2. Install dependencies: bundle install

3. (Optional) Set your vault path via environment variable (recommended): export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"

4. Start the MCP server: ruby obsidian_server.rb

5. (Optional) Verify using MCP Inspector: npx @modelcontextprotocol/inspector ./obsidian_server.rb

Environment variable OBSIDIAN_VAULT_PATH enables automatic vault discovery. If not set, the server will attempt discovery via its default logic (e.g., looking for a common vault location). Ensure the vault directory is accessible by the Ruby process. Docker-based deployment is supported as described in the README, and the server can be integrated with Claude Desktop by wiring the path to obsidian_server.rb and providing OBSIDIAN_VAULT_PATH in env in your Claude config. If you encounter issues with notes containing frontmatter or special characters, ensure your Ruby environment supports UTF-8 and that the vault contains a valid notes structure. The project includes a comprehensive test suite; running bundle exec rspec will execute tests for vault parsing, search, and tools behavior.