Obsidian MCP Server

Integrations

  • Enables AI models to interact with Obsidian vaults through a standardized interface, providing file operations, search capabilities, and property management for knowledge bases in Obsidian

Obsidian MCP Server

A Model Context Protocol server designed for LLMs to interact with Obsidian vaults. Built with TypeScript and featuring secure API communication, efficient file operations, and comprehensive search capabilities, it enables AI assistants to seamlessly manage knowledge bases through a clean, flexible tool interface.

The Model Context Protocol (MCP) enables AI models to interact with external tools and resources through a standardized interface.

Requires the Local REST API plugin in Obsidian.

📋 Table of Contents

Features | Installation | Configuration | Tools | Resources | Project Structure | Contributing | Publishing | License

✨ Features

  • File Operations: Atomic file/directory operations with validation, resource monitoring, and error handling.
  • Search System: Full-text search with configurable context, advanced JsonLogic queries, glob patterns, and frontmatter field support.
  • Property Management: YAML frontmatter parsing, intelligent merging, automatic timestamps, and custom field support.
  • Security & Performance: API key authentication, rate limiting, SSL options, resource monitoring, and graceful shutdown.

🚀 Installation

Note: Requires Node.js and the Local REST API plugin enabled in Obsidian.

Option 1: Clone and Build (for development or direct use)

  1. Enable the Local REST API plugin in Obsidian.
  2. Clone the repository, install dependencies, and build the project:
    git clone git@github.com:cyanheads/obsidian-mcp-server.git cd obsidian-mcp-server npm install npm run build
  3. Configure the server using environment variables (see Configuration section below).
  4. Configure your MCP client settings (e.g., claude_desktop_config.json or cline_mcp_settings.json) to include the server. See the Configuration section for details.

Option 2: Install via npm (as a dependency or globally)

  1. Enable the Local REST API plugin in Obsidian.
  2. Install the package using npm:
    # Install locally (e.g., within another project) npm install obsidian-mcp-server # Or install globally npm install -g obsidian-mcp-server
  3. Configure your MCP client settings (e.g., claude_desktop_config.json or cline_mcp_settings.json) to include the server. See the Configuration section for details.

⚙️ Configuration

Add to your MCP client settings (e.g., claude_desktop_config.json or cline_mcp_settings.json):

{ "mcpServers": { "obsidian-mcp-server": { "command": "node", "args": ["/path/to/obsidian-mcp-server/dist/index.js"], "env": { "OBSIDIAN_API_KEY": "your_api_key_here", "VERIFY_SSL": "false", "OBSIDIAN_PROTOCOL": "https", "OBSIDIAN_HOST": "127.0.0.1", "OBSIDIAN_PORT": "27124", "REQUEST_TIMEOUT": "5000", "MAX_CONTENT_LENGTH": "52428800", "MAX_BODY_LENGTH": "52428800", "RATE_LIMIT_WINDOW_MS": "900000", "RATE_LIMIT_MAX_REQUESTS": "200", "TOOL_TIMEOUT_MS": "60000" } } } }

Environment Variables:

  • OBSIDIAN_API_KEY (Required): Your API key from Obsidian's Local REST API plugin settings.
  • VERIFY_SSL (Default: false): Enable SSL verification. Set to false for self-signed certificates or local use.
  • OBSIDIAN_PROTOCOL (Default: "https"): Protocol (http or https).
  • OBSIDIAN_HOST (Default: "127.0.0.1"): Host address.
  • OBSIDIAN_PORT (Default: 27124): Port number.
  • REQUEST_TIMEOUT (Default: 5000): Request timeout (ms).
  • MAX_CONTENT_LENGTH (Default: 52428800 [50MB]): Max response content length (bytes).
  • MAX_BODY_LENGTH (Default: 52428800 [50MB]): Max request body length (bytes).
  • RATE_LIMIT_WINDOW_MS (Default: 900000 [15 min]): Rate limit window (ms).
  • RATE_LIMIT_MAX_REQUESTS (Default: 200): Max requests per window.
  • TOOL_TIMEOUT_MS (Default: 60000 [1 min]): Tool execution timeout (ms).

🛠️ Tools

ToolDescriptionParameters
obsidian_list_files_in_vaultLists all files and directories within the root of your Obsidian vault. Returns a hierarchical structure detailing files, folders, and their types.None
obsidian_list_files_in_dirLists files and directories within a specific folder in your Obsidian vault. Returns a hierarchical structure. Note: Empty directories may not be included in the results. Useful for exploring vault organization.dirpath*: Path to list files from (relative to vault root). Note that empty directories will not be returned.
obsidian_get_file_contentsRetrieves the full content of a specified file within your Obsidian vault. Supports various readable file formats.filepath*: Path to the relevant file (relative to your vault root).
obsidian_append_contentAppends the provided content to the end of a specified file in the vault. If the file does not exist, it will be created.filepath*: Path to the file (relative to vault root)content*: Content to append to the file
obsidian_update_contentOverwrites the entire content of a specified file in the vault with the provided content. If the file does not exist, it will be created.filepath*: Path to the file (relative to vault root)content*: The new, complete content for the file (overwrites existing content).
obsidian_find_in_filePerforms a full-text search across all files in your Obsidian vault. Returns matching files with context around each match. If more than 5 files match, only filenames and match counts are returned to avoid excessive output. Ideal for locating specific text, tags, or patterns.query*: Text pattern to search for. Can include tags, keywords, or phrases.contextLength: Number of characters surrounding each match to provide context (default: 10).
obsidian_complex_searchFinds files based on path patterns using JsonLogic queries. Primarily supports glob for pattern matching (e.g., '*.md') and var for accessing the 'path' variable. Note: For content-based searches (full-text, tags within content, dates), use obsidian_find_in_file.query*: A JsonLogic query object targeting file paths. Example: {"glob": ["*.md", {"var": "path"}]} matches all markdown files.
obsidian_get_tagsRetrieves all tags defined in the YAML frontmatter of markdown files within your Obsidian vault, along with their usage counts and associated file paths. Optionally, limit the search to a specific folder.path: Optional folder path (relative to vault root) to restrict the tag search.
obsidian_get_propertiesRetrieves properties (like title, tags, status) from the YAML frontmatter of a specified Obsidian note. Returns all defined properties, including any custom fields.filepath*: Path to the note file (relative to vault root)
obsidian_update_propertiesUpdates properties within the YAML frontmatter of a specified Obsidian note. By default, array properties (like tags, type, status) are merged; use the 'replace' option to overwrite them instead. Handles custom fields and manages timestamps automatically. See schema for supported standard fields (title, author, tags, status, etc.).filepath*: Path to the note file (relative to vault root)properties*: Properties to updatereplace: If true, array properties (like tags, status) will be completely replaced with the provided values instead of being merged with existing values. Defaults to false (merge).

🔗 Resources

ResourceDescriptionReturns
obsidian://tagsList of all tags used across the Obsidian vault with their usage countsapplication/json

📁 Project Structure

The project follows a modular architecture with clear separation of concerns:

src/ ├── index.ts # Main entry point ├── mcp/ # MCP server implementation ├── obsidian/ # Obsidian API client and types ├── resources/ # MCP resource implementations ├── tools/ # MCP tool implementations │ ├── files/ # File operations tools │ ├── search/ # Search tools │ └── properties/ # Property management tools └── utils/ # Shared utilities

👥 Contributing

  1. Fork the repository
  2. Create a feature branch
  3. Submit a Pull Request

For bugs and features, create an issue at https://github.com/cyanheads/obsidian-mcp-server/issues.

📄 License

Apache License 2.0


-
security - not tested
A
license - permissive license
-
quality - not tested

hybrid server

The server is able to function both locally and remotely, depending on the configuration or use case.

Enables interaction between LLMs and Obsidian vaults through the Model Context Protocol, supporting secure file operations, content management, and advanced search capabilities.

  1. 📋 Table of Contents
    1. ✨ Features
      1. 🚀 Installation
        1. Option 1: Clone and Build (for development or direct use)
        2. Option 2: Install via npm (as a dependency or globally)
      2. ⚙️ Configuration
        1. 🛠️ Tools
          1. 🔗 Resources
            1. 📁 Project Structure
              1. 👥 Contributing
                1. 📄 License

                  Related MCP Servers

                  • A
                    security
                    A
                    license
                    A
                    quality
                    A Model Context Protocol server that enables LLMs to interact with Salesforce data through SOQL queries, SOSL searches, and various API operations including record management.
                    Last updated -
                    10
                    53
                    Python
                    MIT License
                  • A
                    security
                    A
                    license
                    A
                    quality
                    Adds powerful Hacker News integration to LLM clients, allowing users to access stories, comments, user profiles, and search functionality through the Model Context Protocol.
                    Last updated -
                    9
                    25
                    4
                    JavaScript
                    MIT License
                  • -
                    security
                    A
                    license
                    -
                    quality
                    A Model Context Protocol server enabling LLMs to search, retrieve, and manage documents through Rememberizer's knowledge management API.
                    Last updated -
                    19
                    Python
                    Apache 2.0
                  • -
                    security
                    A
                    license
                    -
                    quality
                    A Model Context Protocol server that enables AI assistants to read, write, and manipulate notes in your Obsidian vault through a standardized interface.
                    Last updated -
                    598
                    TypeScript
                    ISC License

                  View all related MCP servers

                  ID: syuh40cxyk