📌Overview

Purpose: The Obsidian MCP Server serves as a bridge for Large Language Models (LLMs) to navigate and interact with Obsidian vaults efficiently.

Overview: This server is built using TypeScript and implements the Model Context Protocol (MCP), allowing AI assistants to perform knowledge management tasks such as file operations, search functionalities, and property management within Obsidian vaults in a secure and effective manner.

Key Features:

• File Operations: Facilitates atomic file and directory actions, ensuring validation and error handling for robust performance.

• Search System: Provides full-text search capabilities along with advanced JSON logic queries to filter files and metadata, adapting to user needs effectively.

---

Obsidian MCP Server

A Model Context Protocol server designed for LLMs to interact with Obsidian vaults. Built with TypeScript, it features secure API communication, efficient file operations, and comprehensive search capabilities, enabling AI assistants to manage knowledge bases seamlessly.

Features

File Operations

• Atomic file/directory operations with validation
• Resource monitoring and cleanup
• Error handling and graceful failure

Search System

• Full-text search with configurable context
• Advanced JsonLogic queries for files, tags, and metadata
• Support for glob patterns and frontmatter fields

Property Management

• YAML frontmatter parsing and intelligent merging
• Automatic timestamps (created by Obsidian, modified by server)
• Custom field support

Security & Performance

• API key authentication with rate limiting and SSL options
• Resource monitoring and health checks
• Graceful shutdown handling

Installation

Requirements: Node.js

1. Enable Local REST API plugin in Obsidian

2. Clone and build:

   git clone git@github.com:cyanheads/obsidian-mcp-server.git
   cd obsidian-mcp-server
   npm install
   npm run build
   

   Or install from npm:

   npm install obsidian-mcp-server
   

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/build/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:

• Required:

  • OBSIDIAN_API_KEY: Your API key from Obsidian's Local REST API plugin settings

• Connection Settings:

  • VERIFY_SSL: Enable SSL certificate verification (default: false)
  • OBSIDIAN_PROTOCOL: Protocol to use (default: "https")
  • OBSIDIAN_HOST: Host address (default: "127.0.0.1")
  • OBSIDIAN_PORT: Port number (default: 27124)

• Request Limits:

  • REQUEST_TIMEOUT: Request timeout in milliseconds (default: 5000)
  • MAX_CONTENT_LENGTH: Maximum response content length in bytes (default: 52428800 [50MB])
  • MAX_BODY_LENGTH: Maximum request body length in bytes (default: 52428800 [50MB])

• Rate Limiting:

  • RATE_LIMIT_WINDOW_MS: Rate limit window in milliseconds (default: 900000 [15 minutes])
  • RATE_LIMIT_MAX_REQUESTS: Maximum requests per window (default: 200)

• Tool Execution:

  • TOOL_TIMEOUT_MS: Tool execution timeout in milliseconds (default: 60000 [1 minute])

Project Structure

The project follows a modular architecture with a 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
  └── utils/            # Shared utilities

Tools

File Management

• List vault contents
• Get file contents

Search Operations

• Text search with context
• Advanced search with JsonLogic

Content Modification

• Append to file
• Update file content

Property Management

• Get note properties
• Update note properties

Best Practices

• Use atomic operations with validation.
• Handle errors and monitor performance.
• Validate inputs and handle errors gracefully.

Contributing

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

For bugs and features, create an issue at GitHub Issues.

Publishing

The package is automatically published to npm when version tags are pushed:

# Update version in package.json
npm version patch  # or minor, or major
git push --follow-tags

License

Apache License 2.0