Obsidian MCP Server

Connect your Obsidian vault to Amp and supercharge your note-taking with AI

Use Amp (Sourcegraph's AI coding assistant) to automatically create, update, and manage notes in your Obsidian vault. Perfect for documentation, learning logs, code snippets, and building a knowledge base as you code.

🚀 Now with 121 comprehensive tools for complete Obsidian automation!

---

✨ Features

🎯 What's New in v4.0

• 🎨 Canvas Integration - Create and manipulate Obsidian Canvas boards programmatically
• 📊 Dataview Queries - Execute database-like queries on your vault
• 🌐 Graph Analysis - Analyze knowledge networks, find clusters, calculate centrality
• 🔗 Advanced URI Generation - Create deep links to Obsidian (obsidian:// URIs)
• 📎 Enhanced Attachments - Better media file management
• 🔍 Advanced Search & Replace - Regex search, frontmatter search, vault-wide refactoring
• 🏷️ Enhanced Metadata - Advanced frontmatter manipulation and batch updates
• 📚 Structured Templates - Pre-formatted note types (books, people, meetings, projects)
• ✅ Enhanced Task Management - Filter by criteria, add metadata, generate reports
• 📐 Advanced Formatting - Callouts, tables, TOC, Mermaid diagrams, LaTeX math
• 🔧 Vault Maintenance - Health analysis, find duplicates, cleanup automation
• 🔄 Cross-Note Analysis - Compare, merge, split notes intelligently

Core Capabilities

• 🤖 AI-Powered Note Creation - Let Amp create structured notes for you
• 📝 Code Snippet Library - Automatically save code with syntax highlighting
• 🧠 Knowledge Graphs - Build interconnected notes with automatic linking
• 📊 Thread Summaries - Save your Amp conversations for future reference
• 🔍 Vault Search - Search notes by content, tags, metadata, regex
• 🏷️ Smart Tagging - Automatic categorization and organization
• 🔗 Cross-Referencing - Link related notes automatically
• 📈 Analytics - Vault statistics, health reports, insights
• 💾 Export Everything - PDF, HTML, JSON, CSV, Markdown bundles

---

🚀 Quick Start

Prerequisites

• Node.js v18 or higher
• Amp installed
• Obsidian installed (recommended)

Installation

1. Clone the repository:

   git clone https://github.com/Kynlos/Obsidian-MCP.git
   cd Obsidian-MCP
   

2. Install dependencies:

   npm install
   

3. Run the setup wizard:

   npm run setup
   

   The setup wizard will:

   • Prompt you for your Obsidian vault path
   • Create a .env configuration file
   • Configure Amp automatically for your platform (Windows/macOS/Linux)

4. Restart Amp

5. Test it:

   npm test
   

   Or in Amp:

   You: "Create a note in Obsidian called 'Test' with content 'Hello from Amp!'"
   

---

⚙️ Configuration

Workspace-Relative Vaults (New!)

By default, vaults are created in your current workspace directory - no hardcoded paths needed!

# Optional: Override defaults
VAULTS_BASE_PATH=/path/to/your/vaults/folder
OBSIDIAN_VAULT_PATH=/path/to/your/default/vault

Automatic Setup (Recommended)

Run the setup wizard to configure everything automatically:

npm run setup

Manual Setup

1. Copy .env.example to .env:

   cp .env.example .env
   

2. Configure Amp by editing the config file:

   • Windows: %APPDATA%\Amp\mcp-config.json
   • macOS/Linux: ~/.config/amp/mcp-config.json

   Add this configuration:

   {
     "mcpServers": {
       "obsidian": {
         "command": "node",
         "args": ["/absolute/path/to/Obsidian-MCP/index.js"]
       }
     }
   }
   

3. Restart Amp

---

🛠️ Available Tools

The Obsidian MCP provides 121 powerful tools organized into 14 categories:

🎨 Canvas Integration (6 tools)

Create and manipulate Obsidian Canvas files (JSON-based visual boards).

Tool	Description
create_canvas	Create new canvas JSON files
add_card_to_canvas	Add text/note/media cards to canvas
add_connection_to_canvas	Connect cards with lines/arrows
create_canvas_group	Group cards together
read_canvas	Parse and read canvas structure
update_canvas_card	Modify existing canvas cards

📊 Dataview Query Execution (3 tools)

Execute database-like queries on your vault (simplified implementation).

Tool	Description
execute_dataview_query	Run Dataview DQL queries and return results
create_dataview_codeblock	Insert dataview query blocks into notes
validate_dataview_query	Check if query syntax is valid

🌐 Graph Analysis (5 tools)

Analyze your knowledge network programmatically.

Tool	Description
generate_graph_data	Build graph structure from vault links (nodes/edges)
find_note_clusters	Identify groups of related notes
calculate_note_centrality	Find most connected/important notes
get_shortest_path	Find link path between two notes
find_isolated_notes	Notes with few/no connections

🔗 Advanced URI Generation (4 tools)

Create obsidian:// deep links for automation and external integrations.

Tool	Description
generate_obsidian_uri	Create obsidian:// URIs for deep linking
create_workspace_uri	Generate URI to open workspace
create_append_uri	Generate URI to append text to note
create_search_uri	Generate URI to search vault

📎 Attachments & Media Management (5 tools)

Manage media files and attachments in your vault.

Tool	Description
list_attachments	List all media files in vault
attach_file	Copy external file into vault attachments folder
delete_attachment	Remove attachment files
find_orphaned_attachments	Find unused media files
get_attachment_references	Find which notes use an attachment

🔍 Advanced Search & Replace (4 tools)

Powerful search and refactoring tools.

Tool	Description
regex_search_and_replace	Find and replace with regex across vault
search_in_frontmatter	Search YAML frontmatter specifically
search_by_link_type	Find specific link patterns (wiki vs markdown)
multi_file_replace	Batch find/replace across multiple notes

🏷️ Enhanced Metadata/Frontmatter (6 tools)

Advanced YAML frontmatter manipulation.

Tool	Description
update_frontmatter_field	Edit specific YAML field without rewriting note
batch_update_metadata	Update property across multiple notes
validate_frontmatter_schema	Check frontmatter against schema
list_all_properties	Get all unique property keys in vault
rename_property_globally	Rename property across all notes
get_property_values	List all values for a property

📚 Structured Content Templates (5 tools)

Create common note types with pre-formatted structures.

Tool	Description
create_from_template_with_prompts	Template with variable substitution
create_book_note	Structured book/literature note
create_person_note	Person/contact note structure
create_meeting_note	Meeting notes with agenda/action items
create_project_note	Project planning note structure

✅ Enhanced Task Management (5 tools)

Advanced task data management beyond basic TODO lists.

Tool	Description
get_tasks_by_criteria	Filter tasks by status, date, priority, tags
move_task_between_notes	Relocate task to different note
add_task_metadata	Add due date, priority, tags to task
create_task_report	Generate task summary/report
find_blocked_tasks	Tasks waiting on dependencies

📐 Advanced Markdown Formatting (6 tools)

Automate tedious formatting tasks.

Tool	Description
convert_to_callout	Wrap text in callout blocks
create_markdown_table	Generate tables programmatically
add_table_of_contents	Generate TOC from headings
create_mermaid_diagram	Generate Mermaid diagrams from data
create_math_block	Add LaTeX math blocks
standardize_formatting	Fix inconsistent markdown formatting

🔧 Vault Maintenance (5 tools)

Keep your vault healthy and organized.

Tool	Description
find_duplicate_notes	Detect similar/duplicate content
find_empty_notes	List notes with no content
find_large_notes	Notes exceeding size threshold
analyze_vault_health	Overall vault statistics/issues
cleanup_broken_references	Remove/fix broken links

🔄 Cross-Note Analysis (5 tools)

Compare, refactor, and reorganize notes.

Tool	Description
compare_notes	Diff two notes
find_similar_notes	Content similarity analysis
track_note_changes	Compare note versions over time
merge_notes_enhanced	Smart merge with options
split_note_by_headings	Break large note into smaller ones

📝 Core Note Creation (4 tools)

Tool	Description
save_code_snippet	Save code with syntax highlighting and metadata
save_thread_summary	Save AI conversation summaries with key insights
save_knowledge_note	Create general knowledge notes with tags
create_daily_note	Create daily notes with optional custom templates

✏️ Core Note Management (5 tools)

Tool	Description
read_note	Read the full content of a note
update_note	Update note content (preserves metadata by default)
delete_note	Delete a note from the vault
append_to_note	Append content to the end of an existing note
rename_note	Rename a note file

---

See complete tool documentation in AGENTS.md

---

💡 Usage Examples

Create a Canvas Board

You: "Create a canvas called 'Project Planning' and add cards for Frontend, Backend, and Database"

Execute Dataview Query

You: "Show me all notes tagged with 'python' created this month"

Generate Obsidian URIs

You: "Create a link I can use to open my Daily Note from outside Obsidian"

Analyze Vault Structure

You: "Show me the most connected notes in my vault and find any isolated notes"

Create Structured Notes

You: "Create a book note for 'The Pragmatic Programmer' by Andy Hunt and Dave Thomas"

Advanced Formatting

You: "Create a Mermaid flowchart showing the authentication process and add it to my Security note"

See 50+ more examples →

---

🔧 Available Commands

Command	Description
npm install	Install dependencies
npm run setup	Run interactive setup wizard
npm test	Test configuration
npm start	Start the MCP server (for debugging)

---

🧪 Testing

Verify your setup is working correctly:

npm test

This will check:

• .env file exists and is valid
• Obsidian vault path is accessible
• Amp configuration is correct
• All dependencies are installed
• Node.js version is compatible

---

📊 Version History

• v4.0.0 (2025-11-13) - MAJOR UPDATE: Added 59 new tools (Canvas, Dataview, Graph Analysis, URIs, and much more!)
• v3.1.0 - Export features (PDF, HTML, JSON, CSV)
• v3.0.0 - Template system and advanced search
• v2.0.0 - Task management and analytics
• v1.0.0 - Initial release

See full changelog →

---

🎯 Platform Support

This MCP works on:

• ✅ Windows (10, 11)
• ✅ macOS (10.15+)
• ✅ Linux (Ubuntu, Debian, Fedora, etc.)

Automatic configuration paths:

• Windows: %APPDATA%\Amp\mcp-config.json
• macOS/Linux: ~/.config/amp/mcp-config.json

---

📚 Documentation

• AGENTS.md - Complete tool reference for AI agents
• SETUP.md - Detailed setup instructions
• EXAMPLES.md - Real-world usage examples
• CONTRIBUTING.md - How to contribute
• CHANGELOG.md - Version history

---

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details.

---

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

---

🔗 Links

• Repository: https://github.com/Kynlos/Obsidian-MCP
• Amp: https://ampcode.com/
• Obsidian: https://obsidian.md/
• MCP Specification: https://modelcontextprotocol.io/

---

🙏 Acknowledgments

• Kynlo for creating the original Obsidian MCP Server
• Sourcegraph for Amp
• Obsidian team for the amazing note-taking app

---

Made with ❤️ for the Amp and Obsidian communities

⭐ Star this repo if you find it useful!