obsidian-mcp-server
by: cyanheads
Model Context Protocol (MCP) server designed for LLMs to interact with Obsidian vaults. Provides secure, token-aware tools for seamless knowledge base management through a standardized interface.
π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 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.
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
Note: Requires Node.js
- Enable Local REST API plugin in Obsidian
- 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
OBSIDIAN_API_KEY
: API key from Obsidian's Local REST API plugin settings (required)VERIFY_SSL
: Enable SSL certificate verification; set tofalse
for self-signed certificates or local runs (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 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
Tools
File Management
// List vault contents
obsidian_list_files_in_vault: {
}
// List directory contents
obsidian_list_files_in_dir: {
dirpath: string; // Path relative to vault root
}
// Get file contents
obsidian_get_file_contents: {
filepath: string; // Path relative to vault root
}
Search Operations
// Text search with context
obsidian_find_in_file: {
query: string,
contextLength?: number // Default: 10
}
// Advanced search with JsonLogic
obsidian_complex_search: {
query: JsonLogicQuery
// Examples:
// Find by tag:
// {"in": ["#mytag", {"var": "frontmatter.tags"}]}
//
// Find markdown files in a directory:
// {"glob": ["docs/*.md", {"var": "path"}]}
//
// Combine conditions:
// {"and": [
// {"glob": ["*.md", {"var": "path"}]},
// {"in": ["#mytag", {"var": "frontmatter.tags"}]}
// ]}
}
// Get all tags in vault or directory
obsidian_get_tags: {
path?: string // Optional: limit to specific directory
}
Content Modification
// Append to file
obsidian_append_content: {
filepath: string, // Path relative to vault root
content: string // Content to append
}
// Update file content
obsidian_patch_content: {
filepath: string, // Path relative to vault root
content: string // New content (replaces existing)
}
Property Management
// Get note properties
obsidian_get_properties: {
filepath: string // Path relative to vault root
}
// Update note properties
obsidian_update_properties: {
filepath: string, // Path relative to vault root
properties: {
title?: string,
author?: string,
// Note: created/modified timestamps are managed automatically
type?: Array<"concept" | "architecture" | "specification" |
"protocol" | "api" | "research" | "implementation" |
"guide" | "reference">,
tags?: string[], // Must start with #
status?: Array<"draft" | "in-progress" | "review" | "complete">,
version?: string,
platform?: string,
repository?: string, // URL
dependencies?: string[],
sources?: string[],
urls?: string[], // URLs
papers?: string[],
custom?: Record<string, unknown>
}
}
Best Practices
File Operations
- Use atomic operations with validation
- Handle errors and monitor performance
Search Implementation
- Use appropriate search tool for the task:
obsidian_find_in_file
for text searchobsidian_complex_search
for metadata/tag filtering
- Keep context size reasonable (default: 10 chars)
Property Management
- Use appropriate types and validate updates
- Handle arrays and custom fields properly
- Never set timestamps (managed automatically)
Error Prevention
- Validate inputs and handle errors gracefully
- Monitor patterns and respect rate limits
Resources
The MCP server exposes the following resource:
obsidian://tags # List of all tags used across the vault
Contributing
- Fork the repository
- Create a feature branch
- Submit a Pull Request
For bugs and feature requests, create an issue at:
https://github.com/cyanheads/obsidian-mcp-server/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
This triggers a GitHub Action to build and publish the package.
License
Apache License 2.0