Obsidian MCP Server

A powerful Model Context Protocol (MCP) server for natural language interaction with your Obsidian vault. Built with TypeScript and designed for seamless integration with Claude Code and other MCP clients.

Features

Core Capabilities

• Natural Language Queries: Ask questions about your vault in plain English
• Advanced Search: Intelligent search with link analysis, tag hierarchies, and structural context
• Backlink Analysis: Find and analyze connections between notes
• Vault Navigation: Browse directory structure and discover notes
• Full CRUD Operations: Read, write, create, append, and update notes

Advanced Intelligence Tools

• Guided Story Path: Generate narrative tours through linked notes
• Note Auditing: Find recently modified notes missing frontmatter or structure
• Contextual Companions: Discover related notes based on links, keywords, and recency
• Fresh Energy: Identify recently updated notes needing integration
• Initiative Bridge: Track project-specific notes with outstanding tasks
• Pattern Echo: Find notes that reuse specific phrasings or patterns
• Synthesis Ready: Detect note clusters that need summary notes

Installation

From Source

1. Clone the repository:

   git clone https://github.com/dbmcco/obsidian-mcp.git
   cd obsidian-mcp
   

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Configuration

Claude Code Setup

Add to your Claude Code MCP configuration:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Claude Desktop Setup

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/absolute/path/to/your/vault"
      }
    }
  }
}

Environment Variables

• OBSIDIAN_VAULT_PATH: Required. Absolute path to your Obsidian vault

Available Tools

Basic Operations

query_vault

Process natural language queries about your vault content.

Example: "What are the main themes in my project notes?"

{
  query: string,
  vaultPath?: string  // Optional override
}

search_notes

Search for notes by filename or content using exact text matching.

{
  searchTerm: string,
  searchType: 'filename' | 'content' | 'both',  // Default: 'both'
  vaultPath?: string
}

intelligent_search

Advanced search with link graph analysis, tag hierarchies, and structural context weighting.

{
  query: string,
  vaultPath?: string
}

list_directories

Browse vault directory structure with note counts.

{
  directoryPath?: string,  // Empty string for vault root
  vaultPath?: string
}

get_note

Retrieve the full content of a specific note.

{
  notePath: string,  // Relative to vault root
  vaultPath?: string
}

get_backlinks

Find all notes that link to a specific note with context.

{
  notePath: string,
  vaultPath?: string
}

Write Operations

write_note

Write or completely overwrite a note.

{
  notePath: string,
  content: string,
  vaultPath?: string
}

create_note

Create a new note with frontmatter and content.

{
  notePath: string,
  title: string,
  content?: string,
  tags?: string[],
  vaultPath?: string
}

append_to_note

Append content to an existing note.

{
  notePath: string,
  content: string,
  vaultPath?: string
}

update_note_section

Update a specific section identified by heading.

{
  notePath: string,
  sectionHeading: string,
  newContent: string,
  vaultPath?: string
}

Advanced Intelligence

guided_path

Generate a narrative tour through linked notes starting from a seed note.

{
  notePath: string,
  supportingLimit?: number,      // Default: 3
  counterpointLimit?: number,    // Default: 3
  includeActionItems?: boolean,  // Default: true
  vaultPath?: string
}

Output: Markdown narrative with introduction, supporting threads, counterpoints, and action items.

audit_recent_notes

Find recently modified notes missing frontmatter or structure.

{
  hoursBack?: number,           // Default: 72
  limit?: number,               // Default: 25
  requiredFields?: string[],    // Default: ['title', 'created']
  requireHeadings?: boolean,    // Default: false
  vaultPath?: string
}

contextual_companions

Discover notes related to a topic or seed note based on links, keywords, and recency.

{
  notePath?: string,    // Optional seed note
  topic?: string,       // Optional topic query
  limit?: number,       // Default: 5
  vaultPath?: string
}

Note: Must provide either notePath or topic.

fresh_energy

Find recently updated notes lacking backlinks or outgoing links (needing integration).

{
  hoursBack?: number,   // Default: 48
  limit?: number,       // Default: 10
  minWords?: number,    // Default: 80
  vaultPath?: string
}

initiative_bridge

Track project/initiative-tagged notes with outstanding tasks.

{
  initiative: string,           // Required: project identifier
  frontmatterField?: string,    // Default: 'project'
  limit?: number,               // Default: 10
  vaultPath?: string
}

pattern_echo

Find notes that reuse specific phrasings, bullet patterns, or framework fragments.

{
  snippet: string,      // Required: text pattern to find
  limit?: number,       // Default: 5
  vaultPath?: string
}

synthesis_ready

Detect clusters of interlinked notes that lack a summary/synthesis note.

{
  minClusterSize?: number,  // Default: 3
  vaultPath?: string
}

Example Use Cases

Knowledge Discovery

// Find all notes about a topic with intelligent expansion
await intelligentSearch({ query: "machine learning" });

// Discover related notes for further reading
await contextualCompanions({
  topic: "neural networks",
  limit: 10
});

Vault Maintenance

// Audit recent work for missing metadata
await auditRecentNotes({
  hoursBack: 168,  // Last week
  requiredFields: ['title', 'created', 'tags']
});

// Find orphaned notes needing links
await freshEnergy({ hoursBack: 72 });

// Identify note clusters needing synthesis
await synthesisReady({ minClusterSize: 4 });

Project Management

// Track all tasks for a specific project
await initiativeBridge({
  initiative: "Project Alpha",
  frontmatterField: "project"
});

// Generate a narrative overview of a topic
await guidedPath({
  notePath: "Projects/Project Alpha.md",
  supportingLimit: 5,
  includeActionItems: true
});

Pattern Analysis

// Find notes using a specific framework
await patternEcho({
  snippet: "SWOT Analysis:",
  limit: 10
});

Development

Scripts

• npm run dev: Watch mode for development
• npm run build: Build TypeScript to JavaScript
• npm run start: Start the MCP server

Project Structure

obsidian-mcp/
├── src/
│   ├── index.ts           # MCP server and tool definitions
│   ├── vault-manager.ts   # Vault operations and intelligence
│   └── query-processor.ts # Natural language query processing
├── dist/                  # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md

Technical Details

Architecture

• TypeScript with strict mode enabled
• ES Modules (NodeNext)
• Zod for runtime type validation
• gray-matter for frontmatter parsing
• glob for file pattern matching

Search Methods

The intelligent_search tool combines four search strategies:

1. Direct matching: Exact keyword matches in content/filenames
2. Link proximity: Notes connected via wiki-links
3. Tag expansion: Related notes via tag hierarchies
4. Structural context: Section-aware searching with relevance scoring

Results are merged, deduplicated, and ranked by relevance score.

Performance

• No caching - all searches are real-time to avoid staleness
• Lazy loading of note content for large vaults
• Efficient glob patterns for file discovery

Credits

Built by Braydon with Claude (Anthropic). This MCP server was developed using test-driven development principles and extensive collaboration with Claude Code.

License

MIT License - feel free to use and modify as needed.

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with tests
4. Submit a pull request

Troubleshooting

"No vault path provided" error

Ensure OBSIDIAN_VAULT_PATH is set in your MCP configuration or environment variables.

MCP server not connecting

• Verify the path to dist/index.js is absolute, not relative
• Ensure the server is built (npm run build)
• Check that Node.js can execute the script

Search returns no results

• Verify vault path is correct
• Check that .md files exist in the vault
• Try using list_directories to explore the vault structure