# Obsidian MCP Server

[![Tests](https://github.com/Piotr1215/mcp-obsidian/actions/workflows/test.yml/badge.svg)](https://github.com/Piotr1215/mcp-obsidian/actions/workflows/test.yml)
[![codecov](https://codecov.io/gh/Piotr1215/mcp-obsidian/graph/badge.svg)](https://codecov.io/gh/Piotr1215/mcp-obsidian)
[![MCP Compliant](https://img.shields.io/badge/MCP-Compliant-green)](./MCP_SPEC_COMPLIANCE.md)

MCP server for Obsidian that provides secure, direct file system access to vault files.

## Why This Server?

Most existing Obsidian MCP servers rely on the Obsidian REST API plugin, which requires:
- Obsidian to be installed
- Obsidian to be running
- The REST API plugin to be configured

This server instead works directly with Obsidian vault files on disk, making it compatible with setups using [obsidian.nvim](https://github.com/obsidian-nvim/obsidian.nvim) - a Neovim plugin that provides Obsidian-like features without requiring the Obsidian app.

## Features

- **Direct file system access** to Obsidian vaults - no Obsidian app required
- **Security-first design** with path traversal prevention and input validation
- **High performance** with execution time tracking and resource limits
- **Rich search capabilities** including regex support and tag-based search
- **Metadata support** with frontmatter and inline tag parsing

## Recent Updates

### 🎉 New Features
- **🗺️ MOC Discovery**: New `discover-mocs` tool provides a high-level map of your vault's knowledge structure by discovering Maps of Content and their relationships. **Start here for 10x faster navigation!**
- **Resource Links**: Search results now include MCP resource links for direct note access
- **Context Snippets in Search Results**: Search results now include surrounding lines for better context understanding
- **Match Highlighting**: Search terms are highlighted with **bold** markers in results
- **Improved Search Result Structure**: Results are now grouped by file with match counts and snippets

## Installation

```bash
npm install
```

## Usage

### Testing with MCP Inspector

```bash
# Replace /home/decoder/dev/obsidian/decoder with your vault path
npx @modelcontextprotocol/inspector node src/index.js /home/decoder/dev/obsidian/decoder
```

The inspector will open at http://localhost:5173

### Running Tests

```bash
# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage report
npm run test:coverage

# Run tests with coverage and check thresholds
npm run coverage

# Run mutation testing (all files)
npm run test:mutation

# Run mutation testing (pagination code only - faster)
npm run test:mutation-pagination
```

### Adding to Claude Desktop

To add this server to Claude Desktop, use the Claude CLI:

```bash
# Clone this repository
git clone https://github.com/Piotr1215/mcp-obsidian.git
cd mcp-obsidian

# Install dependencies
npm install

# Add to Claude (replace /path/to/your/vault with your Obsidian vault path)
claude mcp add obsidian -s user -- node /path/to/mcp-obsidian/src/index.js /path/to/your/vault
```

For example, if you cloned the repo to `~/dev/mcp-obsidian` and your vault is at `~/Documents/ObsidianVault`:

```bash
claude mcp add obsidian -s user -- node ~/dev/mcp-obsidian/src/index.js ~/Documents/ObsidianVault
```

This will add the server to your Claude configuration file (typically `~/.claude.json` or `~/.config/Claude/claude_desktop_config.json`).

To verify the installation:

```bash
claude mcp list
```

You should see `obsidian` in the list of available MCP servers.

## Available Tools

### search-vault
Search for content across all notes in your vault.

**Features:**
- Boolean operators: AND, OR, NOT (also supports &&, ||, -)
- Field specifiers: `title:term`, `content:term`, `tag:term`
- Quoted phrases: `"exact phrase"`
- Grouping with parentheses: `(term1 OR term2) AND term3`
- Case-sensitive/insensitive search
- **Context snippets**: See surrounding lines for each match
- **Match highlighting**: Search terms are highlighted with **bold**
- **Resource links**: Results include MCP resource links for direct note access
- Returns grouped results by file with match counts
- Optional path filtering

**Context Options:**
- `includeContext` (default: true) - Show surrounding lines
- `contextLines` (default: 2) - Number of lines before/after match (0-10)

**Examples:**
- `readme AND install` - Find notes containing both words
- `title:setup OR tag:documentation` - Find by title or tag
- `"getting started" -deprecated` - Exact phrase, excluding deprecated
- `(python OR javascript) AND tutorial` - Complex queries with grouping

**Example Output with Context:**
```json
{
  "files": [{
    "path": "notes/dotfiles.md",
    "matchCount": 3,
    "matches": [{
      "line": 42,
      "content": "Managing my dotfiles with stow",
      "context": {
        "lines": [
          { "number": 40, "text": "## Configuration Management", "isMatch": false },
          { "number": 41, "text": "", "isMatch": false },
          { "number": 42, "text": "Managing my dotfiles with stow", "isMatch": true },
          { "number": 43, "text": "has simplified my setup process.", "isMatch": false },
          { "number": 44, "text": "", "isMatch": false }
        ],
        "highlighted": "Managing my **dotfiles** with stow"
      }
    }]
  }],
  "totalMatches": 43,
  "fileCount": 15
}
```

### search-by-title
Search for notes by their H1 title (# Title).
- Fast title-based search
- Case-sensitive/insensitive matching
- Returns title, file path, and line number
- **Resource links**: Results include MCP resource links for direct note access
- Optional path filtering
- Only matches H1 headings (single #)

### list-notes
List all markdown files in your vault or a specific directory.
- Returns file paths and total count
- **Resource links**: Results include MCP resource links for direct note access
- Supports directory filtering

### read-note
Read the complete content of a specific note.
- **Wikilink-style resolution**: Just provide the filename (e.g., `bitwarden-cli.md`) and the server finds it anywhere in the vault
- Falls back to exact path if provided (e.g., `Notes/projects/bitwarden-cli.md`)
- Reports ambiguity if multiple notes share the same filename
- Path validation ensures security
- File size limits prevent memory issues

### write-note
Create or update a note with new content.
- Atomic writes for data integrity
- Automatic directory creation
- Content size validation

### delete-note
Delete a note from your vault. Permanent, there is no trash.

Clients that support MCP elicitation are asked to confirm first, and the prompt
shows the note's size, modification date and first line, read off disk rather
than taken from the caller's argument. Refusing keeps the note and the tool
reports that it did not delete. A decline, a cancel, a timeout and a dead
transport all count as a refusal.

Some clients advertise elicitation and then answer it themselves without showing
anyone. Codex 0.153.4 returns a decline in about 10ms on its programmatic tool
path. The note is kept either way, and the tool says the client answered rather
than blaming you for a prompt you never saw.

Clients that do not advertise elicitation delete without a prompt, as before.
Set `OBSIDIAN_MCP_CONFIRM_DELETE=off` to turn the prompt off for clients that
do.

### append-note
Add content to an existing note without overwriting it, creating the note if it
is absent. `write-note` replaces the whole file; this one does not.

- `section` appends under a specific heading rather than at the end
- `ensureNewline` (default true) keeps the appended block from running into the
  previous line


### search-by-tags
Find notes containing specific tags.
- Supports both YAML frontmatter and inline #tags
- AND operation for multiple tags
- **Resource links**: Results include MCP resource links for direct note access
- Case-sensitive/insensitive matching

### get-note-metadata
Get metadata for one or all notes without reading full content.
- Single note mode: Get metadata for a specific note
- Batch mode: Get metadata for all notes in vault
- Extracts frontmatter, title, tags, and content preview
- **Resource links**: Results include MCP resource links for direct note access
- Lightweight alternative to reading full notes
- Useful for building note indexes or dashboards

### discover-mocs
**⭐ RECOMMENDED: Start here!** Discover MOCs (Maps of Content) to understand your vault's knowledge structure.

[Maps of Content](https://notes.linkingyourthinking.com/Cards/MOCs+Overview) are organizational hub notes (tagged with `#moc`) that link to related content. They were pioneered by [Nick Milo](https://www.linkingyourthinking.com/) as a flexible alternative to rigid folder structures.

**Features:**
- Lists all MOCs in your vault with their linked notes
- Shows MOC hierarchy (which MOCs link to other MOCs)
- Displays full list of wikilinks from each MOC
- **Provides a high-level map** of your vault's organization
- **10x faster navigation** - understand structure before searching
- Filter by MOC name or directory

**Why use MOCs?**
- **Context**: See what knowledge areas exist in your vault
- **Scale**: Understand how developed each area is
- **Relationships**: Discover how topics connect through MOC hierarchy
- **Entry points**: Find the best starting point for exploration

**Example Output:**
```
Found 10 MOCs

📚 Vault Index (24 linked notes)
   Path: 00-INDEX.md
   Links: Work-MOC, AI-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Personal-MOC, Homelab-MOC, MCP-Framework-MOC
   🔗 Links to MOCs: Work-MOC, AI-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Personal-MOC, Homelab-MOC, MCP-Framework-MOC

📚 AI-MOC (61 linked notes)
   Path: _mocs/AI-MOC.md
   Links: chatgpt, ollama, langchain, aider, gp-nvim, MCP-Framework-MOC, ...
   🔗 Links to MOCs: MCP-Framework-MOC, Development-MOC, DevOps-MOC, Tools-MOC, Work-MOC, 00-INDEX
```

This tool enables agents to understand your knowledge graph structure instantly, making navigation ~10x faster than blind keyword searching.

## Security Features

This server implements comprehensive security measures:

- **Path Traversal Prevention**: All file paths are validated to prevent access outside the vault
- **Input Validation**: All inputs validated against JSON schemas
- **File Size Limits**: Configurable limits prevent memory exhaustion (default: 10MB)
- **Content Sanitization**: Removes potentially harmful null bytes
- **Markdown-only Access**: Only `.md` files can be accessed
- **Human Confirmation Before Deletion**: `delete-note` asks the user over MCP elicitation, so the go-ahead comes from a person rather than from an argument the model composed. Path validation stops a traversal but not a deletion of the wrong note inside the vault; this is what covers that.

See [MCP_SPEC_COMPLIANCE.md](./MCP_SPEC_COMPLIANCE.md) for detailed compliance information.

## Contributing

1. Ensure all tests pass: `npm test`
2. Maintain test coverage above 90%: `npm run coverage`
3. Follow functional programming principles
4. Add tests for new features
5. Update documentation as needed