# Obsidian MCP Server

A modern Model Context Protocol (MCP) server that integrates with the Obsidian Local REST API to read, create, and edit notes effectively within Obsidian.

## Features

This MCP server provides the following tools:

### Vault File Operations

| Tool | Description |
|------|-------------|
| `vault_get_file` | Get file content (raw markdown, JSON with metadata, or document map) |
| `vault_create_file` | Create or completely replace a file |
| `vault_append_to_file` | Append content to an existing or new file |
| `vault_patch_file` | Partially update a file (heading/block/frontmatter operations) |
| `vault_delete_file` | Delete a file from the vault |

### Directory Operations

| Tool | Description |
|------|-------------|
| `vault_list` | List files and directories in the vault |

### Search Operations

| Tool | Description |
|------|-------------|
| `search_simple` | Simple text search with context |
| `search_advanced` | Advanced search using Dataview DQL or JsonLogic |

## Prerequisites

1. **Obsidian** with the **Local REST API** plugin installed and enabled
2. **Node.js** v18 or higher
3. API Key from Obsidian's Local REST API settings

## Quick Start

```bash
npm install
npm run build
npm run setup
```

The interactive setup wizard will guide you through:
- Entering your Obsidian API Key
- Selecting transport mode (stdio for Claude Desktop, HTTP for Open WebUI)
- Configuring optional settings

After setup, start the server:

```bash
# For Open WebUI (HTTP mode)
npm run start:http

# For Claude Desktop (stdio mode)
npm start
```

## Installation

```bash
npm install
npm run build
```

## Configuration

### Setup Wizard (Recommended)

Run the interactive setup wizard:

```bash
npm run setup
```

This creates a `.env` file with your configuration.

### Manual Configuration

Alternatively, copy `.env.example` to `.env` and edit manually:

```bash
cp .env.example .env
```

### Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `OBSIDIAN_API_URL` | Obsidian REST API URL | `http://127.0.0.1:27123` |
| `OBSIDIAN_API_KEY` | API Key | (required) |
| `MCP_TRANSPORT` | `stdio` or `http` | `stdio` |
| `MCP_PORT` | Port for HTTP mode | `3000` |
| `DEBUG` | Enable debug logging | `false` |

## Usage with MCP Clients

### Claude Desktop (stdio mode)

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/Obsidian_MCP/dist/index.js"],
      "env": {
        "OBSIDIAN_API_URL": "http://127.0.0.1:27123",
        "OBSIDIAN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### Open WebUI (HTTP mode)

1. Start the server in HTTP mode:
   ```bash
   npm run start:http
   ```

2. In Open WebUI, go to **Admin Settings** → **Tools** → **MCP Servers**

3. Add a new MCP server:
   - **Type**: MCP Streamable HTTP
   - **URL**: `http://localhost:3000/mcp`
   - **Auth**: None (the server handles Obsidian auth internally)

4. Click **Save**

## Startup Health Check

When the server starts, it automatically verifies the connection to Obsidian:

```
========================================
  Obsidian MCP Server - Startup Check
========================================
API URL: http://127.0.0.1:27123
Debug Mode: disabled

Checking connection to Obsidian REST API...
✓ Connected to Obsidian REST API
✓ Authenticated successfully
  Plugin Version: 3.4.2
  Obsidian Version: 1.11.7
```

If there are connection issues, troubleshooting steps are displayed.

## Debug Mode

Enable debug logging for verbose output:

```bash
DEBUG=true npm start
```

Shows detailed logs for API requests, tool calls, and HTTP connections.

## Troubleshooting

### Open WebUI Connection Failed

1. **Verify server is running**:
   ```bash
   curl http://localhost:3000/health
   ```

2. **Check configuration**:
   - URL: `http://localhost:3000/mcp`
   - Auth: **None** (not Bearer)
   - Type: MCP Streamable HTTP

3. **Test the endpoint**:
   The `/mcp` endpoint accepts POST requests with MCP protocol messages.

### General Issues

1. Ensure Obsidian is running with Local REST API plugin enabled
2. Verify API key is correct
3. Try `DEBUG=true npm start` for detailed logs
4. Re-run setup: `npm run setup`

## Tool Details

### vault_get_file

Get file content with optional format:
- `markdown` (default): Raw markdown content
- `json`: Parsed note with metadata
- `document-map`: Shows headings, blocks, frontmatter fields

### vault_patch_file

Partial updates without rewriting entire file:
- **Operations**: `append`, `prepend`, `replace`
- **Targets**: headings, block references, frontmatter fields

### search_advanced

- **Dataview DQL**: `TABLE FROM #tag WHERE field = value`
- **JsonLogic**: `{"in": ["myTag", {"var": "tags"}]}`

## Development

```bash
# Build
npm run build

# Development with auto-rebuild
npm run dev          # stdio mode
npm run dev:http     # HTTP mode

# Setup wizard
npm run setup

# Clean build artifacts
npm run clean
```

## License

MIT