Skip to main content
Glama
obsidian-mcp

obsidian-mcp

Obsidian MCP Server

An MCP (Model Context Protocol) server that provides access to your Obsidian vault, enabling seamless interaction with your notes, documents, and knowledge base.

Features

  • File Discovery: List all files in your Obsidian vault

  • Content Reading: Read the full content of any file in your vault

  • File Search: Find files by name or path patterns

  • Content Search: Search for text within all files in your vault

  • Safe Access: Excludes system directories like .obsidian and .git

  • Large File Handling: Automatically handles large files with size limits and content truncation

Related MCP server: obsidian-mcp

Tools Available

  • list_files() - Get a list of all files in your vault

  • get_file_content(file_path) - Read the content of a specific file

  • find_files(query) - Find files by name matching a query

  • find_in_all_file_content(query) - Search for text within all file contents

Installation

  1. Clone this repository:

    git clone <repository-url>
    cd obsidian-mcp
  2. Install dependencies using uv (recommended) or pip:

    # Using uv
    uv sync
    
    # Or using pip
    pip install -e .

Configuration for Claude Desktop

To use this MCP server with Claude Desktop, you need to add it to your Claude Desktop configuration file.

Windows Configuration

  1. Open your Claude Desktop configuration file at:

    %APPDATA%\Claude\claude_desktop_config.json
  2. Add the following configuration to the mcpServers section:

    {
      "mcpServers": {
        "obsidian-mcp": {
          "command": "uv",
          "args": [
            "run",
            "python",
            "C:\\path\\to\\your\\obsidian-mcp\\main.py",
            "C:\\path\\to\\your\\obsidian\\vault"
          ]
        }
      }
    }

macOS/Linux Configuration

  1. Open your Claude Desktop configuration file at:

    ~/Library/Application Support/Claude/claude_desktop_config.json  # macOS
    ~/.config/claude/claude_desktop_config.json                      # Linux
  2. Add the following configuration to the mcpServers section:

    {
      "mcpServers": {
        "obsidian-mcp": {
          "command": "uv",
          "args": [
            "run",
            "python",
            "/path/to/your/obsidian-mcp/main.py",
            "/path/to/your/obsidian/vault"
          ]
        }
      }
    }

Alternative Configuration (without uv)

If you prefer not to use uv, you can configure it to run directly with Python:

{
  "mcpServers": {
    "obsidian-mcp": {
      "command": "python",
      "args": [
        "/path/to/your/obsidian-mcp/main.py",
        "/path/to/your/obsidian/vault"
      ]
    }
  }
}

Important Notes

  • Replace /path/to/your/obsidian-mcp/main.py with the actual path to the main.py file

  • Replace /path/to/your/obsidian/vault with the actual path to your Obsidian vault directory

  • Use forward slashes (/) in paths even on Windows when using the JSON configuration

  • Restart Claude Desktop after making configuration changes

Usage

Once configured, you can ask Claude to:

  • "List all files in my Obsidian vault"

  • "Show me the content of my daily note from yesterday"

  • "Find all files related to 'project alpha'"

  • "Search for all mentions of 'TODO' in my vault"

  • "What notes do I have about machine learning?"

Claude will use the MCP server to access your vault and provide responses based on your actual notes and documents.

Security

This MCP server provides read-only access to your Obsidian vault. It cannot create, modify, or delete files. It automatically excludes system directories like .obsidian and .git from access.

Development

  • Language: Python 3.11+

  • Framework: FastMCP

  • Dependencies: See pyproject.toml

Development Setup

  1. Install development dependencies:

    uv sync --group dev
  2. Run linting:

    uv run ruff check
    uv run ruff format

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Available Tools

4 tools
find_filesA

Find files in the Obsidian Vault that match a query and return the file paths.

Args:
    query: Search term to match against file names (case-insensitive).
           Can be a partial filename, extension, or keyword.
           Examples: 'meeting', '.md', 'project-alpha'

Returns:
    List of relative file paths that match the query.
    Use these paths with get_file_content() to read the files.
    Returns message if no matches found.

Note: Searches only file names/paths, not file contents. Use find_in_all_file_content()
      to search within file contents.

Inputs: query (required). Returns: result

find_in_all_file_contentA

Find a query in the content of all files in the Obsidian Vault and return the file paths.

Args:
    query: Text to search for within file contents (case-insensitive).
           Can be words, phrases, or partial text.
           Examples: 'meeting notes', 'project deadline', 'TODO'

Returns:
    Newline-separated list of file paths that contain the query text.
    Only returns the file paths, not the matching content excerpts.
    Use get_file_content() on returned paths to read the full files.
    Returns message if no matches found.

Note: Searches the full text content of all readable files. Skips binary files.
      For filename searches, use find_files() instead.

Inputs: query (required). Returns: result

get_file_contentA

Get the content of a file in the Obsidian Vault.

Args:
    file_path: The relative file path from the vault root. Use the exact path
              format returned by list_files() or find_files().
              Examples: 'notes/meeting-notes.md', 'daily/2024-01-15.md'
              This parameter is REQUIRED - you must specify which file to read.

Returns:
    The full text content of the file, or an error message if the file
    cannot be read or doesn't exist.

Note: Only reads text files. Binary files will return an encoding error.

Inputs: file_path (required). Returns: object

list_filesA

List all files in the Obsidian Vault and return their paths.

Returns a newline-separated list of file paths relative to the vault root.
Use these exact paths with get_file_content() to read file contents.
Excludes system directories like .obsidian.

Example return format:
notes/meeting-notes.md
projects/project-alpha.md
daily/2024-01-15.md

Inputs: no named parameters. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 4 tools

    Disambiguation4/5

    Most tools are clearly distinct: list_files lists all files, find_files searches by filename, find_in_all_file_content searches content, and get_file_content reads a specific file. The only potential confusion is between list_files and find_files, but their descriptions clarify the difference.

    Naming Consistency4/5

    All tool names use snake_case and follow a verb_noun pattern (list_files, get_file_content, find_files). One name, find_in_all_file_content, is more verbose but still consistent in style.

    Tool Count4/5

    Four tools is a reasonable count for a read-only Obsidian Vault server. The scope is narrow but sufficient for listing, retrieving, and searching files.

    Completeness4/5

    The tool set covers the common read operations for a Vault: listing files, reading content, and searching by name or content. Missing write operations like create/update/delete, but for a read-only server the surface is functional.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      A
      maintenance
      Standalone MCP server for Obsidian vaults - hybrid search (FTS5 + vector + cross-encoder reranking), images and PDFs in agent-readable form, Kanban-aware tasks (Tasks-plugin + Dataview formats), structured memory with topic recall, fine-grained read/write tools for optimal token efficiency, and link graph support. Run locally, self-host, or one-click deploy for remote access. OAuth 2.1.
      16
      33
      636 npm
      38
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Enables MCP clients to search, read, list, and append to markdown notes in a local Obsidian vault or folder of .md files.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables LLM clients to read, search, and write to a local Obsidian vault over MCP, with full-text search, vault analytics, health scoring, and policy-enforced file operations.
      1
      MIT