Obsidian Ai Curator

Obsidian Plugin Claude AI MCP Server TypeScript License: MIT

The knowledge fragmentation problem: Your insights are scattered across hundreds of notes. The solution: AI-powered consolidation that actively merges related fragments into coherent knowledge. How it works: Claude AI analyzes your Obsidian vault via MCP and intelligently combines scattered thoughts.

What It Does

Gives Claude direct access to your Obsidian vault. Ask Claude to:

• 🔍 "Search for notes about machine learning"
• 📝 "Create a new project note with proper formatting"
• 🏷️ "Find all notes tagged #active that need review"
• 📁 "Move completed projects to archive"
• 🔄 "Create a git checkpoint before making changes"
• 🔗 "Rename this file and update all links"
• 📅 "Add a task to today's daily note"

Quick Start

1. Install MCP Server

git clone https://github.com/nwant/obsidian-ai-curator.git
cd obsidian-ai-curator
npm install

2. Configure Your Vault Path

cp config/config.minimal.json config/config.json

Edit config/config.json and set your vault path:

{
  "vaultPath": "/path/to/your/obsidian/vault"
}

3. Add to Claude Desktop

Edit your Claude Desktop config:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-ai-curator/src/mcp-server.js"]
    }
  }
}

Important: Use the full absolute path, not relative paths or ~

4. Restart Claude Desktop

Completely quit and restart Claude Desktop to load the MCP server.

5. Verify Installation

In Claude, type:

What MCP tools do you have access to?

You should see tools like vault_scan, write_note, search_content, etc.

See Quick Start Guide for detailed instructions and optional plugin setup.

Features

• Search & Query: Natural language search, metadata queries, Dataview integration
• Smart Writing: Auto-formats links, validates tags, manages frontmatter
• File Management: Rename/move files with automatic link updates
• Tag Management: Analyze usage, validate tags, rename globally
• Project Playbooks: Customizable structures for different project types
• Git Integration: Checkpoint and rollback capabilities
• Daily Notes: Quick capture and task management
• 🚀 Automated Workflow: Claude Desktop → GitHub Issues → Claude Code → Pull Requests

See Examples for detailed use cases.

🚀 NEW: Automated Claude Code Integration

Turn errors into fixes and ideas into features - automatically!

This project now includes TWO ways to automate development with Claude Code:

Option 1: Local Execution (Recommended)

Run Claude Code on your machine - no GitHub Actions needed!

# Quick setup
bash scripts/setup-local-claude.sh

# Requirements:
# 1. Install Claude Code CLI from https://claude.ai/code
# 2. Install GitHub CLI: brew install gh
# 3. Authenticate both tools

Benefits:

• ✅ No GitHub Actions costs
• ✅ Runs immediately on your machine
• ✅ Full control and visibility
• ✅ Easy debugging

See Local Claude Code Guide for setup.

Option 2: GitHub Actions Automation

Use GitHub Actions to run Claude Code in the cloud

# Setup GitHub Actions workflow
bash scripts/setup-automation.sh

# Requires Claude Code OAuth token in GitHub Secrets

Benefits:

• ✅ Runs in cloud, not on your machine
• ✅ Triggered automatically by issues
• ✅ Works even when you're offline

See GitHub Actions Workflow Guide for setup.

Documentation

• Quick Start Guide - Get running in 5 minutes
• Local Claude Code - Run Claude Code locally (recommended)
• GitHub Actions Workflow - Cloud-based automation
• Troubleshooting - Common issues and solutions
• Configuration Guide - All configuration options
• MCP Tools Reference - Complete tool API documentation
• Examples - Common use cases and workflows
• Project Playbooks - Creating custom project playbooks
• Obsidian Plugin Guide - Plugin features and setup
• Formatting Rules - Important Obsidian formatting guidelines

Project Structure

This repository contains:

• MCP Server (src/) - Core functionality for Claude integration
• Obsidian Plugin (obsidian-ai-curator-plugin/) - Enhanced API performance
• Documentation (docs/) - Comprehensive guides

Requirements

• Node.js 18+
• Obsidian (for vault)
• Claude Desktop or Claude Code
• Git (optional, for version control features)

Common Issues

"Claude doesn't see the MCP tools"

• Did you restart Claude completely after editing the config?
• Is the path to mcp-server.js absolute in your Claude config?

"Permission denied" errors

• Check that your vault path in config.json is correct
• Ensure you have read/write permissions to your vault

"Cannot find module" errors

• Run npm install in the project directory
• Make sure you're using Node.js 18 or higher

See Troubleshooting Guide for more help.

Testing

This project uses Jest as the test runner with a comprehensive test suite:

# Run all tests
npm test

# Run specific test suites
npm run test:unit        # Unit tests (parallel execution)
npm run test:integration # Integration tests (sequential execution)
npm run test:coverage    # With coverage report
npm run test:watch       # Watch mode for development
npm run test:verbose     # Detailed output

# Additional testing tools
npm run test:benchmark   # Performance benchmarks
npm run test:harness     # Verify test infrastructure

Jest Benefits:

• ✅ Reliable integration tests - No vault conflicts
• ✅ Fast unit tests - 4x parallel execution
• ✅ Enhanced error messages - Better debugging
• ✅ Modern tooling - Watch mode, coverage, verbose output

See test documentation for details on writing and running tests.

Contributing

Contributions welcome! Please read our contributing guidelines before submitting PRs.

License

MIT