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.
- 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
- 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
-
Clone the repository:
git clone https://github.com/dbmcco/obsidian-mcp.git cd obsidian-mcp -
Install dependencies:
npm install
-
Build the project:
npm run build
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"
}
}
}
}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"
}
}
}
}OBSIDIAN_VAULT_PATH: Required. Absolute path to your Obsidian 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 for notes by filename or content using exact text matching.
{
searchTerm: string,
searchType: 'filename' | 'content' | 'both', // Default: 'both'
vaultPath?: string
}Advanced search with link graph analysis, tag hierarchies, and structural context weighting.
{
query: string,
vaultPath?: string
}Browse vault directory structure with note counts.
{
directoryPath?: string, // Empty string for vault root
vaultPath?: string
}Retrieve the full content of a specific note.
{
notePath: string, // Relative to vault root
vaultPath?: string
}Find all notes that link to a specific note with context.
{
notePath: string,
vaultPath?: string
}Write or completely overwrite a note.
{
notePath: string,
content: string,
vaultPath?: string
}Create a new note with frontmatter and content.
{
notePath: string,
title: string,
content?: string,
tags?: string[],
vaultPath?: string
}Append content to an existing note.
{
notePath: string,
content: string,
vaultPath?: string
}Update a specific section identified by heading.
{
notePath: string,
sectionHeading: string,
newContent: string,
vaultPath?: string
}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.
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
}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.
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
}Track project/initiative-tagged notes with outstanding tasks.
{
initiative: string, // Required: project identifier
frontmatterField?: string, // Default: 'project'
limit?: number, // Default: 10
vaultPath?: string
}Find notes that reuse specific phrasings, bullet patterns, or framework fragments.
{
snippet: string, // Required: text pattern to find
limit?: number, // Default: 5
vaultPath?: string
}Detect clusters of interlinked notes that lack a summary/synthesis note.
{
minClusterSize?: number, // Default: 3
vaultPath?: string
}// 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
});// 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 });// 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
});// Find notes using a specific framework
await patternEcho({
snippet: "SWOT Analysis:",
limit: 10
});npm run dev: Watch mode for developmentnpm run build: Build TypeScript to JavaScriptnpm run start: Start the MCP server
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
- TypeScript with strict mode enabled
- ES Modules (NodeNext)
- Zod for runtime type validation
- gray-matter for frontmatter parsing
- glob for file pattern matching
The intelligent_search tool combines four search strategies:
- Direct matching: Exact keyword matches in content/filenames
- Link proximity: Notes connected via wiki-links
- Tag expansion: Related notes via tag hierarchies
- Structural context: Section-aware searching with relevance scoring
Results are merged, deduplicated, and ranked by relevance score.
- No caching - all searches are real-time to avoid staleness
- Lazy loading of note content for large vaults
- Efficient glob patterns for file discovery
Built by Braydon with Claude (Anthropic). This MCP server was developed using test-driven development principles and extensive collaboration with Claude Code.
MIT License - feel free to use and modify as needed.
Contributions welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Submit a pull request
Ensure OBSIDIAN_VAULT_PATH is set in your MCP configuration or environment variables.
- Verify the path to
dist/index.jsis absolute, not relative - Ensure the server is built (
npm run build) - Check that Node.js can execute the script
- Verify vault path is correct
- Check that
.mdfiles exist in the vault - Try using
list_directoriesto explore the vault structure