nkriman/obsidian-nexus

Obsidian Nexus - Obsidian MCP Server

Connect Claude Desktop directly to your Obsidian vault for seamless note management and intelligent family data organization.

Overview

Obsidian Nexus is a Model Context Protocol (MCP) server that gives Claude Desktop direct access to your Obsidian vault. Simply configure your vault path and start managing your family's notes, todos, and knowledge base through natural conversation with Claude.

Key Features

📝 Direct Vault Access

• Read, write, and append to any note in your vault
• Automatic folder creation and organization
• Full markdown support with Obsidian linking

🔍 Intelligent Search

• Search across all notes with context excerpts
• List notes by directory or pattern
• Find information instantly through natural queries

🏠 Family Organization

• Pre-configured folder structure for family data
• Support for Daily Notes, Family members, and Themes
• Zero setup - just point to your vault

🛡️ Simple & Reliable

• No API keys required - Claude Desktop does the AI processing
• Local-only file operations for privacy
• Automatic vault structure creation

Quick Start

1. Installation

git clone https://github.com/nkriman/obsidian-nexus
cd obsidian-nexus
npm install

2. Configuration

Edit config.yaml and set your vault path:

# Update this path to your Obsidian vault
vault_path: "/Users/yourname/Documents/Obsidian/YourVault"

# Optional: Configure family members
family:
  people: ["Nick", "Sarah", "Leo", "Mia"]

3. Add to Claude Desktop

Add to your MCP settings (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "obsidian-nexus": {
      "command": "node",
      "args": ["/path/to/obsidian-nexus/src/index.js"]
    }
  }
}

4. Restart Claude Desktop

That's it! Claude can now access your Obsidian vault.

Available Tools

📖 read_note

Read any note from your vault:

read_note path="Family/Leo.md"

✏️ write_note

Create or update a note:

write_note path="Daily Notes/2025-06-22.md" content="# Today's Activities..."

➕ append_to_note

Add content to an existing note:

append_to_note path="Family/Leo.md" content="## School Update\nGot an A on math test!"

📚 list_notes

List all notes or search by directory:

list_notes directory="Family"

🔍 search_notes

Search for content across your vault:

search_notes query="doctor appointment"

📊 vault_status

Check vault configuration and stats.

Vault Structure

Obsidian Nexus automatically creates this organized structure:

YourVault/
├── Daily Notes/
│   └── 2025-06-22.md          # Daily family logs
├── Family/
│   ├── Leo.md                 # Individual family member notes
│   ├── Mia.md
│   └── Nick.md
├── Themes/
│   ├── Medical.md             # Topical organization
│   ├── School.md
│   └── Travel.md
├── inbox/
│   └── quick-notes.md         # Temporary storage
└── config/
    └── obsidian-nexus.yaml    # Local configuration

Example Interactions

📝 Daily Family Logging

"Create a note for today about Leo's soccer practice and Mia's piano lesson"

Claude will:

1. Create Daily Notes/2025-06-22.md
2. Add structured content about both activities
3. Link to individual family member notes

🔍 Finding Information

"When was Leo's last doctor appointment and what did they say?"

Claude will:

1. Search across all notes for "Leo" + "doctor"
2. Find relevant excerpts with context
3. Provide a summary with source citations

📊 Organizing Knowledge

"Help me organize all the medical information scattered across my notes"

Claude will:

1. Search for medical-related content
2. Create organized theme notes
3. Update family member notes with proper links

Configuration Options

Basic Configuration

vault_path: "/path/to/your/vault"    # Required: Your Obsidian vault path

family:
  people: ["Name1", "Name2"]         # Optional: Family member tracking

templates:
  daily_note: "Daily Notes/{{date}}.md"
  person_note: "Family/{{person}}.md"
  theme_note: "Themes/{{theme}}.md"

Advanced Options

structure:
  create_folders: true    # Auto-create folder structure
  use_daily_notes: true   # Enable daily notes pattern
  backup_files: true      # Keep backups of modified files

Use Cases

🏠 Family Life Management

• Track kids' activities, appointments, and milestones
• Organize medical records and school communications
• Create searchable family knowledge base

📚 Personal Knowledge Management

• Research note organization and synthesis
• Project documentation and planning
• Learning logs and study materials

💼 Work & Projects

• Meeting notes and action items
• Project documentation and progress tracking
• Team knowledge sharing and collaboration

Benefits Over Manual Obsidian

🤖 AI-Powered Organization

• Claude understands context and relationships
• Automatic note structure and linking
• Intelligent content synthesis

⚡ Speed & Efficiency

• Natural language commands vs. manual clicking
• Instant search across entire vault
• Batch operations and smart suggestions

🔗 Seamless Integration

• Works alongside Obsidian app
• Preserves all Obsidian features and plugins
• Standard markdown - no vendor lock-in

Troubleshooting

Common Issues

"Configuration file not found"

• Ensure config.yaml exists in project root
• Check vault path is absolute and correct

"Vault path does not exist"

• Verify the path points to a valid directory
• Create the directory if it doesn't exist

"Permission denied"

• Check file/folder permissions on vault directory
• Ensure Obsidian app isn't locking files

Testing Your Setup

# Test the server directly
node src/index.js

# Check configuration
vault_status

Privacy & Security

• Local-only processing - no cloud dependencies
• File-based operations - standard markdown files
• No API keys required - Claude Desktop handles AI processing
• Open source - full code transparency

Roadmap

• Advanced templating system
• Plugin integration support
• Multi-vault management
• Real-time sync with Obsidian app
• Advanced search with tags and metadata
• Export/import utilities

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

License

MIT License - see LICENSE file for details.

Obsidian Nexus - Your vault, Claude's intelligence, perfect harmony.