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

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

1. 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

1. 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

1. 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

1. 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.