# Obsidian MCP Server

A Model Context Protocol (MCP) server that provides AI assistants with full-text search access to your Obsidian vault.

## Features

- **Full-text search** across all notes using Whoosh search engine
- **Tag-based filtering** and search
- **Frontmatter support** - extracts and indexes YAML metadata
- **Wikilink parsing** - understands Obsidian's `[[note]]` syntax
- **Real-time updates** - watches vault for changes and updates index automatically
- **No Obsidian plugins required** - works directly with filesystem
- **Fast and efficient** - pure Python implementation with optimized indexing

## Installation

### Option 1: Local Installation

1. Clone this repository:
```bash
git clone <repository-url>
cd obsidianMCP
```

2. Install dependencies:
```bash
# Basic installation
pip install -e .

# Or install from requirements
pip install -r requirements.txt

# For development (includes testing tools)
pip install -r requirements-dev.txt
# OR
pip install -e ".[dev]"

# For reproducible installs using lock files (requires uv)
uv pip sync requirements.lock              # Production dependencies only
uv pip sync requirements-dev.lock          # With development dependencies
```

### Option 2: Docker

1. Clone this repository:
```bash
git clone <repository-url>
cd obsidianMCP
```

2. Build the Docker image:
```bash
docker build -t obsidian-mcp-server .
```

3. Run with Docker:
```bash
docker run -it --rm \
  -e OBSIDIAN_VAULT_PATH=/vault \
  -v /path/to/your/obsidian/vault:/vault:ro \
  -v obsidian-index:/app/index \
  obsidian-mcp-server
```

Or use Docker Compose:
```bash
# Edit docker-compose.yml to set your vault path
docker-compose up -d
```

## Usage

### Environment Setup

Set the required environment variable:
```bash
export OBSIDIAN_VAULT_PATH="/path/to/your/obsidian/vault"
```

Optional environment variables:
```bash
export OBSIDIAN_INDEX_PATH="/path/to/index"  # Default: vault/.obsidian-mcp-index
export OBSIDIAN_MAX_RESULTS=50               # Default: 50
export OBSIDIAN_AUTO_REBUILD_INDEX=true      # Default: true
export OBSIDIAN_INCREMENTAL_UPDATE=true      # Default: true
export OBSIDIAN_WATCH_CHANGES=true           # Default: true
export OBSIDIAN_INCLUDE_CONTENT=true         # Default: true
export OBSIDIAN_USE_POLLING_OBSERVER=false   # Default: false (set to true for Docker/network drives)
```

### Running the Server

```bash
obsidian-mcp-server
```

Or with command line arguments:
```bash
obsidian-mcp-server --vault-path /path/to/vault --max-results 100
```

### Claude Desktop Integration

#### Local Installation
Add to your Claude Desktop configuration (`~/.config/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "obsidian-mcp-server",
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}
```

#### Docker Integration
For Docker, you'll need to create a wrapper script since Claude Desktop needs to communicate via stdio. Create a script like:

```bash
#!/bin/bash
# obsidian-mcp-docker.sh
docker run -i --rm \
  -e OBSIDIAN_VAULT_PATH=/vault \
  -v /path/to/your/obsidian/vault:/vault:ro \
  -v obsidian-index:/app/index \
  obsidian-mcp-server
```

Then configure Claude Desktop to use this script:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "/path/to/obsidian-mcp-docker.sh"
    }
  }
}
```

## Available Tools

### search_notes
Search through your notes using full-text search.

**Parameters:**
- `query` (required): Search query string
- `tags` (optional): Array of tags to filter by
- `limit` (optional): Maximum results (default: 10)

### get_note
Retrieve the full content of a specific note.

**Parameters:**
- `identifier` (required): Note path or title

### list_recent_notes
Get recently modified notes.

**Parameters:**
- `limit` (optional): Maximum results (default: 10)

### get_all_tags
List all available tags in the vault.

### search_by_tag
Find notes with specific tags.

**Parameters:**
- `tags` (required): Array of tags to search for
- `limit` (optional): Maximum results (default: 20)

### get_vault_stats
Get statistics about the vault and search index.

## Architecture

- **Parser** (`parser.py`): Parses markdown files and extracts frontmatter, tags, and wikilinks
- **Search Index** (`search.py`): Whoosh-based full-text search with metadata support
- **File Watcher** (`watcher.py`): Monitors vault for changes and updates index incrementally
- **MCP Server** (`server.py`): Implements the Model Context Protocol interface
- **Configuration** (`config.py`): Handles configuration from environment variables

## Development

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=src/obsidian_mcp

# Generate HTML coverage report
pytest --cov=src/obsidian_mcp --cov-report=html

# Run specific test file
pytest tests/test_parser.py
```

### Code Formatting

```bash
black src/
isort src/
```

### Type Checking

```bash
mypy src/
```

## Multi-Machine Usage

**Perfect for users who sync vaults across multiple machines!**

### Intelligent Index Updates
- **Incremental updates**: Only re-indexes files that have changed since last run
- **Fast startup**: Skips full rebuild when vault hasn't changed
- **Cross-machine sync**: Works with Obsidian Sync, iCloud, Dropbox, git, etc.

### How It Works
1. **First run**: Builds complete search index
2. **Subsequent runs**: Compares file modification times
3. **Only updates changed files**: Fast startup even with large vaults
4. **Handles file moves/renames**: Maintains search accuracy

### Configuration for Multi-Machine
```bash
# Recommended settings for synced vaults
export OBSIDIAN_INCREMENTAL_UPDATE=true    # Enable smart updates
export OBSIDIAN_AUTO_REBUILD_INDEX=true    # Auto-rebuild if needed
export OBSIDIAN_WATCH_CHANGES=true         # Real-time updates while running
```

## Troubleshooting

### Index Issues
If search results seem outdated, the server automatically rebuilds the index on startup. You can also delete the index directory to force a complete rebuild.

### Multi-Machine Sync
- Index files are local to each machine (not synced)
- Vault content is synced between machines
- Each machine maintains its own optimized index

### Permission Issues
Ensure the server has read access to your Obsidian vault directory.

### Performance
For large vaults (>10,000 notes), consider:
- Reducing `max_results` for faster queries
- Using more specific search terms
- Filtering by tags to narrow results
- Incremental updates are especially beneficial for large vaults

## License

MIT License