# Obsidian Tools MCP Server

An extended MCP (Model Context Protocol) server for Obsidian with full CRUD operations and advanced note management capabilities.

## Features

### Core Operations
- **create_note** - Create new notes with nested folder support
- **delete_note** - Delete notes from your vault
- **update_note** - Replace entire note content
- **append_to_note** - Append content to end of notes
- **prepend_to_note** - Prepend content (respects frontmatter)
- **rename_note** - Move/rename notes

### Search & Discovery
- **read_note** - Read single note content
- **search_notes** - Search by filename (supports regex)
- **search_content** - Full-text search in note contents
- **list_folder** - List notes and subfolders

### Links & Tags
- **get_tags** - Extract all tags from a note
- **get_links** - Get all wikilinks and markdown links
- **get_backlinks** - Find notes linking to a specific note

### Advanced Operations
- **insert_at_heading** - Insert content under a specific heading
- **update_frontmatter** - Modify YAML frontmatter properties
- **create_from_template** - Create notes from templates with variable substitution

## Installation

### Prerequisites
- Node.js 18+
- An Obsidian vault

### Setup

```bash
# Clone the repository
git clone https://github.com/yourusername/obsidian-tools-mcp.git
cd obsidian-tools-mcp

# Install dependencies
npm install

# Build the project
npm run build
```

## Configuration

### For VS Code / GitHub Copilot

Add to your VS Code settings (`settings.json`):

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

### For Claude Desktop

Add to your Claude config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

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

### Environment Variables

| Variable | Description | Required |
|----------|-------------|----------|
| `OBSIDIAN_VAULT_PATH` | Absolute path to your Obsidian vault | Yes |

You can also pass the vault path as a command-line argument:

```bash
node dist/index.js /path/to/your/vault
```

## Usage Examples

### Create a New Note

```
Create a note at "Projects/My Project.md" with content about project planning
```

### Search and Update

```
Find all notes containing "TODO" and append a completion timestamp
```

### Template-Based Creation

```
Create a new meeting note from the template at "Templates/Meeting.md" 
with title "Q4 Planning Session"
```

### Frontmatter Management

```
Update the frontmatter of "My Note.md" to add tags: ["project", "important"]
```

## Tool Reference

### create_note
Create a new note in the vault.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path relative to vault root |
| content | string | Yes | Markdown content |
| overwrite | boolean | No | Overwrite if exists (default: false) |

### delete_note
Delete a note from the vault.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |

### update_note
Replace the entire content of a note.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |
| content | string | Yes | New content |

### append_to_note
Append content to the end of a note.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |
| content | string | Yes | Content to append |
| separator | string | No | Separator before content (default: "\n\n") |

### prepend_to_note
Prepend content to a note (after frontmatter if present).

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |
| content | string | Yes | Content to prepend |
| separator | string | No | Separator after content (default: "\n\n") |

### rename_note
Move or rename a note.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| oldPath | string | Yes | Current path |
| newPath | string | Yes | New path |

### search_notes
Search notes by filename pattern.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | Yes | Search pattern (regex supported) |
| limit | number | No | Max results (default: 20) |

### search_content
Search for text within note contents.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| query | string | Yes | Text to search for |
| caseSensitive | boolean | No | Case sensitivity (default: false) |
| limit | number | No | Max results (default: 20) |

### get_tags
Get all tags from a note.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |

### get_links
Get all internal links from a note.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |

### get_backlinks
Find all notes linking to a specific note.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |

### insert_at_heading
Insert content under a specific heading.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |
| heading | string | Yes | Heading text to find |
| content | string | Yes | Content to insert |
| position | "start" \| "end" | No | Where to insert (default: "end") |

### update_frontmatter
Update YAML frontmatter properties.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| path | string | Yes | Path to the note |
| properties | object | Yes | Key-value pairs (use null to delete) |

### create_from_template
Create a note from a template.

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| templatePath | string | Yes | Path to template note |
| newPath | string | Yes | Path for new note |
| variables | object | No | Template variable substitutions |

**Built-in template variables:**
- `{{date}}` - Current date (YYYY-MM-DD)
- `{{time}}` - Current time (HH:MM:SS)
- `{{datetime}}` - ISO datetime

## Development

```bash
# Watch mode for development
npm run dev

# Build
npm run build

# Run directly
npm start
```

## License

MIT