# Obsidian MCP Server

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

Use [Amp](https://ampcode.com/) (Sourcegraph's AI coding assistant) to automatically create, update, and manage notes in your [Obsidian](https://obsidian.md/) 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](https://nodejs.org/) v18 or higher
- [Amp](https://ampcode.com/) installed
- [Obsidian](https://obsidian.md/) installed (recommended)

### Installation

1. **Clone the repository:**
   ```bash
   git clone https://github.com/Kynlos/Obsidian-MCP.git
   cd Obsidian-MCP
   ```

2. **Install dependencies:**
   ```bash
   npm install
   ```

3. **Run the setup wizard:**
   ```bash
   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:**
   ```bash
   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!

```env
# 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:
```bash
npm run setup
```

### Manual Setup

1. Copy `.env.example` to `.env`:
   ```bash
   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:
   ```json
   {
     "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](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 →](EXAMPLES.md)**

---

## 🔧 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:

```bash
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 →](CHANGELOG.md)**

---

## 🎯 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](AGENTS.md)** - Complete tool reference for AI agents
- **[SETUP.md](SETUP.md)** - Detailed setup instructions
- **[EXAMPLES.md](EXAMPLES.md)** - Real-world usage examples
- **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute
- **[CHANGELOG.md](CHANGELOG.md)** - Version history

---

## 🤝 Contributing

Contributions are welcome! Please read our [Contributing Guide](CONTRIBUTING.md) for details.

---

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](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](https://ampcode.com/)
- **Obsidian** team for the amazing note-taking app

---

**Made with ❤️ for the Amp and Obsidian communities**

⭐ Star this repo if you find it useful!