Obsidian Research

A Model Context Protocol (MCP) server enabling Claude to read, write, search, and analyse your Obsidian vault with advanced research capabilities.

🌟 Core Capabilities

8 consolidated tools providing comprehensive vault operations:

🧠 Semantic Search

Find notes conceptually related to "machine learning interpretability" 
with high precision matching

• Smart Connections integration for concept-based search
• Advanced filtering by folders, tags, linked files, frontmatter properties
• Link expansion with configurable traversal depth
• Similarity thresholds for precision control

🔍 Pattern Search

Extract all TODO items and incomplete tasks across my vault, 
showing where they appear and usage statistics

• Multiple regex patterns with frequency analysis
• Context windows around matches
• Scoped searching with include/exclude filters
• Usage statistics and insights

📄 Note Operations

Get my "AI Ethics" note with creation date, file size, 
and word count in structured JSON format

• Batch retrieval of multiple notes efficiently
• File statistics with formatted timestamps and token counts
• JSON/Markdown formats with comprehensive metadata
• Auto-resolution from basenames to full paths

✏️ Precision Writing

Add new findings section after the "Results" heading 
in my research paper without disrupting the structure

• Surgical positioning relative to headings, frontmatter, or line ranges
• Whole-file operations (overwrite, append, prepend)
• Automatic frontmatter preservation
• Active note targeting for current Obsidian file

🗂️ Vault Exploration

Show me all recent markdown files in my Projects folder, 
excluding drafts and temporary files

• Advanced filtering by extension, date range, name patterns
• Content statistics for text files (word count, line count)
• Recursive exploration with configurable depth
• Overview/detailed modes for different use cases

🔗 Relationship Analysis

Map all the connections between my project notes - 
which ones reference each other and how they're linked

• Comprehensive relationship types: backlinks, forward links, tags, mentions, embeds
• Batch analysis across multiple files
• Contextual evidence with line numbers and surrounding text
• Strength scoring and filtering thresholds

📊 Content Analysis

Break down the structure of my research paper and 
extract just the "Results" section with its subsections

• Document structure extraction (headings, lists, code blocks, tasks, tables)
• Advanced section targeting by heading text, line ranges, or regex patterns
• Hierarchical analysis with parent/child relationships
• Rich metadata including word counts and content classification

🔧 File Management

Rename my project file and automatically update 
all the links pointing to it throughout my vault

• Link-aware operations automatically updating all references
• Batch text operations with regex and smart case preservation
• Safety features: dry-run preview, backups, comprehensive error handling
• Find-replace across vault with flexible scoping

🚀 Quick Setup

Prerequisites

• Node.js 18+
• Obsidian with Local REST API and Smart Connections plugins

Installation

1. Install Dependencies

   # In Obsidian: Install "Local REST API" and "Smart Connections" plugins
   # Enable Local REST API (starts on port 27124, note the API key)
   

2. Build MCP Server

   git clone <repository-url>
   cd obsidian-research-mcp
   npm install && npm run build
   

3. Install Obsidian Plugin

   cp -r packages/obsidian-plugin/ /path/to/vault/.obsidian/plugins/obsidian-research-mcp/
   # Enable "Research MCP Bridge" in Obsidian settings
   

4. Configure Claude Desktop

   Use the plugin's "Configure Claude Desktop" command or manually add to claude_desktop_config.json:

   {
     "mcpServers": {
       "obsidian-research-mcp": {
         "command": "node",
         "args": ["/path/to/obsidian-research-mcp/packages/mcp-server/dist/index.js"],
         "env": {
           "OBSIDIAN_API_KEY": "your_api_key_from_local_rest_api",
           "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
           "OBSIDIAN_VAULT_PATH": "/path/to/your/vault"
         }
       }
     }
   }
   

5. Test Connection

   Restart Claude Desktop and ask: "Can you read my Obsidian notes?"
   

🏗️ Architecture

Claude Desktop ←→ MCP Server ←→ Local REST API ←→ Obsidian Vault
                      ↓
               Smart Connections

• Obsidian Plugin: Bridges Local REST API with Smart Connections
• MCP Server: Standalone process with 8 consolidated tools
• Local Communication: HTTPS on localhost (port 27124)
• Link Integrity: Automatic maintenance across all operations

🔍 Example Workflows

Research Analysis

1. Find notes about "neural networks" using semantic search
2. Analyse relationships between the top 3 results  
3. Extract all citations and TODOs from these notes
4. Create a summary note with findings

Content Organisation

1. Explore my Research folder for files modified this month
2. Find all incomplete tasks using pattern search
3. Update the project status in my dashboard note
4. Rename and reorganise files whilst maintaining links

Knowledge Discovery

1. Search for concepts related to my current research using Smart Connections
2. Map relationships between key papers and notes
3. Identify knowledge gaps and missing connections
4. Generate new research questions and next steps

🛡️ Security & Performance

• Local-only communication - no external network access required
• SSL/HTTPS with certificate bypass for self-signed certificates
• Rate limiting and comprehensive error handling
• Cached indices for efficient relationship analysis
• Batch operations for optimal performance

---

Transform your Obsidian vault into an intelligent research assistant with Claude.