# Obsidian MCP Server

Enables MCP clients (e.g., Claude Desktop) to interact with Obsidian vaults seamlessly.

## Features

- **Multi-Vault Support**: Access unlimited Obsidian vaults without per-vault configuration
- **Auto-Discovery**: Automatically discovers REST API credentials from plugin configuration
- **Concurrent-Safe**: File locking prevents data corruption during simultaneous access
- **Hybrid Access**: Filesystem operations (always available) + REST API integration (optional)
- **Security-First**: Path validation, rate limiting, command allowlist, and secure credential handling
- **Zero-Config**: Works immediately with filesystem access; REST API features activate when plugin is installed

## Installation

### From Source (Current)

Currently, installation from source is required:

```bash
git clone <repository-url>
cd obsidian-mcp-server
npm install
npm run build
```

### Via NPM (Coming Soon)

Once published to npm, you'll be able to install globally:

```bash
npm install -g obsidian-mcp-server
```

**Note**: The package is not yet published. Use "From Source" installation for now.

## Quick Start

### 1. Basic Setup (Filesystem Access Only)

The server automatically detects and configures your Obsidian vaults on first run! No manual configuration needed.

**What happens automatically:**
- Config file is created at `~/.config/mcp-obsidian/config.json` (macOS/Linux) or `%APPDATA%/mcp-obsidian/config.json` (Windows)
- Server scans common locations (Documents, Dropbox, iCloud, etc.) for Obsidian vaults
- Discovered vault paths are automatically added to the configuration
- Ready to use immediately!

**Common locations scanned:**
- `~/Documents/Obsidian`
- `~/Dropbox` and subdirectories
- `~/Library/CloudStorage/Dropbox` (macOS)
- `~/Library/Mobile Documents/iCloud~md~obsidian` (macOS)
- `~/OneDrive/Documents/Obsidian` (Windows)

**Note**: You can override the config location by setting the `MCP_OBSIDIAN_CONFIG` environment variable.

This enables immediate access to all discovered vaults using filesystem operations.

### 2. Enable REST API Features (Optional)

Install the [Obsidian Local REST API plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) in your vault:

1. Open Obsidian Settings → Community Plugins
2. Browse and install "Local REST API"
3. Enable the plugin
4. The plugin will generate an API key automatically

No additional configuration needed - the server will auto-discover the credentials.

### 3. Connect to Claude

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

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"]
    }
  }
}
```

**Note**: The `env` section is optional. If omitted, the server uses the default config location (`~/.config/mcp-obsidian/config.json`). Only add it if you want to use a custom config path:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "MCP_OBSIDIAN_CONFIG": "/custom/path/to/config.json"
      }
    }
  }
}
```

Restart Claude Desktop.

## Configuration

**Most users don't need to configure anything!** The server auto-detects your vaults on first run.

### Manual Configuration (Optional)

If you need to customize settings or add vaults in non-standard locations, edit `~/.config/mcp-obsidian/config.json`:

**Minimal Configuration:**
```json
{
  "defaultVaultPath": "/Users/yourname/Documents/Obsidian"
}
```

**Full Configuration:**

See `config.example.json` for a complete configuration with all options:

- **defaultVaultPath**: Base directory containing your vaults
- **vaults**: Named vault mappings for easy access
- **security**: Path restrictions, rate limits, allowed hosts/ports
- **features**: File locking, caching, file watching settings
- **logging**: Log level and sensitive data sanitization

### Named Vaults

For easier access, define named vaults in your config:

```json
{
  "defaultVaultPath": "/Users/yourname/Documents/Obsidian",
  "vaults": {
    "personal": "PersonalVault",
    "work": "WorkVault"
  }
}
```

Then reference them by name in Claude: `"vault": "personal"` instead of full paths.

## Available Tools

### File Operations

- **list_vaults**: List all accessible vaults
- **get_vault_info**: Get vault metadata (file count, plugin status)
- **list_files**: List files in a vault (supports recursive, hidden files)
- **get_file**: Read file content with optional frontmatter parsing
- **write_file**: Write or update files with conflict detection
- **append_content**: Append content to existing files
- **search_files**: Search with regex, case sensitivity, context
- **get_metadata**: Extract frontmatter, tags, links, word count

### Obsidian Integration (Requires REST API Plugin)

- **execute_command**: Execute whitelisted Obsidian commands
- **open_file**: Open files in Obsidian UI
- **get_active_file**: Get currently active file
- **open_graph**: Open graph view

### Allowed Commands

For security, only these Obsidian commands are allowed:

- `graph:open`, `graph:open-local`
- `editor:toggle-source`
- `app:go-back`, `app:go-forward`
- `global-search:open`
- `workspace:new-file`, `file-explorer:reveal-active-file`
- `workspace:split-vertical`, `workspace:split-horizontal`

## Testing

### Test with Claude Desktop

1. Restart Claude Desktop after configuration
2. Open a conversation and try:

```
List my Obsidian vaults
```

Expected response: List of discovered vaults with metadata.

```
Read the file "Daily Notes/2026-01-14.md" from my Personal vault
```

Expected response: File content with metadata.

```
Search for "project" in my Work vault
```

Expected response: Search results with context.

### Test with MCP Inspector

```bash
npx @modelcontextprotocol/inspector dist/index.js
```

This opens a web interface to test all tools interactively.

### Verify File Locking

Open a file in Obsidian and simultaneously have Claude read/write it. The server will handle concurrent access safely with file locking.

### Verify Auto-Discovery

Install the REST API plugin in a vault, then:

```
Get info about my Personal vault
```

Expected response should include `"hasRestApi": true` and `"pluginVersion": "1.x.x"`.

## Architecture

### Hybrid Provider System

```
Operation Request
       ↓
   Router Decision
       ↓
   ┌───┴───┐
   ↓       ↓
Filesystem  REST API
Provider    Provider
   ↓           ↓
 Direct      Plugin
 File I/O    Commands
```

- **Filesystem Provider**: Always available, handles read/write/search
- **REST API Provider**: Optional, handles UI integration and commands
- **Operation Router**: Intelligently selects the appropriate provider

### Security Layers

1. **Path Validation**: Prevents directory traversal, validates symlinks
2. **Rate Limiting**: Global, per-vault, and per-operation limits
3. **Command Allowlist**: Only whitelisted Obsidian commands allowed
4. **Credential Security**: Memory-only cache, no disk serialization

### Concurrent Access Handling

- **File Locking**: Read locks (shared) and write locks (exclusive)
- **Conflict Detection**: Timestamp verification before writes
- **Atomic Writes**: Write to temp file, then rename
- **Lock Timeout**: Automatic cleanup of expired locks

## Troubleshooting

### Vaults Not Found

**Problem**: `list_vaults` returns empty array

**Solutions**:
- **First check**: Restart Claude Desktop to trigger auto-detection
- Verify `defaultVaultPath` in config points to correct directory
- Ensure vaults have `.obsidian` directory (valid Obsidian vaults)
- Check `security.allowedVaultPaths` includes the vault location
- If your vaults are in a non-standard location, manually add the path to `allowedVaultPaths` in the config

### REST API Features Not Working

**Problem**: "REST API required but plugin not installed"

**Solutions**:
- Install "Local REST API" plugin in Obsidian
- Enable the plugin in Obsidian settings
- Verify plugin created `data.json` in `.obsidian/plugins/obsidian-local-rest-api/`
- Clear credential cache: restart the MCP server

### File Lock Timeout

**Problem**: "Could not acquire write lock"

**Solutions**:
- Close files in Obsidian that are being edited
- Wait for ongoing operations to complete
- Increase `features.fileLocking.timeout` in config
- Check for stuck locks: restart the server

### Rate Limit Exceeded

**Problem**: "Rate limit exceeded"

**Solutions**:
- Wait before retrying
- Increase rate limits in config if legitimate usage
- Check for loops in your Claude interactions

### Permission Denied

**Problem**: "Vault path not in allowed directories"

**Solutions**:
- **First try**: Delete `~/.config/mcp-obsidian/config.json` and restart to trigger auto-detection
- Manually add vault path to `security.allowedVaultPaths` in the config
- Use absolute paths, not relative paths
- Check symlink targets are also in allowed paths
- Ensure the path exists and is accessible

## Security Considerations

### Threat Model

This server operates locally and assumes:
- The local machine is trusted
- Claude Desktop is trusted
- Only you have access to the MCP server process

### Protections Implemented

- **Path Traversal Prevention**: Rejects `..` and `~` patterns, validates all paths
- **API Key Security**: Credentials stored only in memory, never logged
- **Command Injection Prevention**: Explicit allowlist of safe commands only
- **Rate Limiting**: Prevents abuse and DoS scenarios
- **Symlink Validation**: Resolves and validates symlink targets
- **Host/Port Validation**: Only localhost connections allowed

### What This Does NOT Protect Against

- Malicious code in your Obsidian vault (markdown files can't execute code)
- Attacks on Obsidian itself
- Physical access to your machine
- Compromised Claude Desktop application

## Development

### Build

```bash
npm run build
```

### Watch Mode

```bash
npm run watch
```

### Run Tests

```bash
npm test
```

### Lint

```bash
npm run lint
```

## Contributing

Contributions welcome! Please:

1. Follow existing code style (TypeScript, ESLint, Prettier)
2. Add tests for new features
3. Update documentation
4. Ensure security best practices

## License

MIT

## Support

For issues, questions, or feature requests, please open an issue on the repository.

## Credits

Built with:
- [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)
- [gray-matter](https://github.com/jonschlinkert/gray-matter) for frontmatter parsing
- [axios](https://github.com/axios/axios) for HTTP requests