# Obsidian MCP Server

A lightweight [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that enables AI assistants like Claude Desktop to securely interact with your Obsidian vault.

`★ Insight ─────────────────────────────────────`

**What this server does:**
- Acts as a secure bridge between AI clients and your Obsidian vault
- Exposes 6 tools for reading, creating, and modifying notes (down from 15!)
- Supports web scraping with automatic HTML→Markdown conversion
- Enables semantic search across your vault

**Key design decisions:**
- Uses **Bun** for zero-build-step TypeScript execution
- Communicates via **stdio** (standard input/output) for security
- Requires **Obsidian Local REST API** plugin for vault access
- No external schema validation library (native TypeScript only)

`─────────────────────────────────────────────────`

## Prerequisites

1. **[Bun](https://bun.sh/)** v1.0 or higher
2. **[Obsidian](https://obsidian.md/)** with the **[Local REST API](https://github.com/coddingtonbear/obsidian-local-rest-api)** plugin installed
3. **[Claude Desktop](https://claude.ai/download)** (or any MCP-compatible client)

## Installation

### 1. Install dependencies

```bash
bun install
```

### 2. Configure the Local REST API plugin in Obsidian

1. Open Obsidian Settings → Community Plugins → Local REST API
2. Enable the plugin
3. Copy your API key

### 3. Configure Claude Desktop

Choose one of the following setup methods:

#### Option A: Per-Project Configuration

Create or edit the Claude Desktop config file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "bun",
      "args": ["/absolute/path/to/obsidian-mcp/src/index.ts"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_API_URL": "http://127.0.0.1:27124"
      }
    }
  }
}
```

#### Option B: Global Configuration (Recommended for Claude Code)

Make Obsidian tools available to **all** Claude Code sessions:

1. Create the global MCP config directory:
   ```bash
   mkdir -p ~/.config/claude
   ```

2. Create `~/.config/claude/mcp_config.json`:
   ```json
   {
     "mcpServers": {
       "obsidian": {
         "command": "bun",
         "args": ["/absolute/path/to/obsidian-mcp/src/index.ts"],
         "env": {
           "OBSIDIAN_API_KEY": "your-api-key-here",
           "OBSIDIAN_API_URL": "http://127.0.0.1:27124"
         }
       }
     }
   }
   ```

3. Verify installation:
   ```bash
   claude mcp list
   ```

The tools are now available in any Claude Code session without additional setup!

### 4. Restart Claude Desktop

The server will start automatically when you launch Claude Desktop.

## Available Tools

The 15 original tools have been consolidated into 6 more powerful tools:

| Tool | Description |
|------|-------------|
| `active_file` | Get/update/append/patch/delete the currently open note |
| `vault_file` | Get/create/append/delete any file in your vault |
| `search_vault` | Search with simple text, Dataview DQL, or JsonLogic |
| `list_vault_files` | List files in a vault directory |
| `open_file_in_obsidian` | Open a file in the Obsidian UI |
| `fetch_webpage` | Fetch a public webpage and convert to Markdown |

### Tool Details

#### `active_file`
Perform operations on the currently active note in Obsidian.

**Parameters:**
- `operation` (required): `get` | `update` | `append` | `patch` | `delete`
- `format`: `markdown` (default) | `json` (for get operation)
- `content`: Content for update/append/patch operations
- `targetType`: For patch - `heading` | `block` | `frontmatter`
- `target`: For patch - target identifier
- Additional patch options: `targetDelimiter`, `trimTargetWhitespace`, `contentType`

#### `vault_file`
Perform operations on files in your vault by path.

**Parameters:**
- `operation` (required): `get` | `create` | `append` | `delete`
- `filename` (required): The file path (can include subdirectories)
- `format`: `markdown` (default) | `json` (for get operation)
- `content`: Content for create/append operations

#### `search_vault`
Search your vault using simple text, Dataview DQL, or JsonLogic.

**Parameters:**
- `queryType` (required): `simple` | `dataview` | `jsonlogic`
- `query` (required): The search query
- `contextLength`: Characters of context around matches (simple search only, default: 100)

#### `list_vault_files`
List files in a vault directory.

**Parameters:**
- `directory`: Optional subdirectory path (omit for root)

#### `open_file_in_obsidian`
Open a file in the Obsidian UI.

**Parameters:**
- `filename` (required): The file path to open
- `newLeaf`: Open in a new pane/tab (default: false)

#### `fetch_webpage`
Fetch a public webpage and convert to Markdown.

**Parameters:**
- `url` (required): The URL to fetch
- `maxLength`: Limit response length (default: 5000)
- `startIndex`: Starting index for pagination (default: 0)
- `raw`: Return raw HTML instead of Markdown (default: false)

## Usage Examples

### Ask Claude to work with your notes

```
"Read my current note and summarize it"
"What tags do I have in my vault?"
"Search my notes for 'machine learning'"
"Create a new note called 'Research Project' with the following outline..."
"Fetch https://example.com and save it as a note"
```

## Development

Run directly with Bun:

```bash
# Set environment variables
export OBSIDIAN_API_KEY="your-key"
export OBSIDIAN_API_URL="http://127.0.0.1:27124"

# Run the server
bun run src/index.ts
```

### Code Quality

```bash
# Run tests
bun test

# Type checking
bun run typecheck

# Linting
bun run lint
bun run lint:fix

# Formatting
bun run format
bun run format:check
```

## Security

This project follows a **source-code transparency** security model. See [SECURITY.md](SECURITY.md) for full details.

**Key security features:**
- Local execution only (communicates via stdio, no network exposure)
- API keys never logged or exposed
- SSRF protection (blocks internal network access)
- Input validation on all parameters
- No telemetry or external network calls
- 30-second timeout on all API requests

**Why this is secure for open-source distribution:**
- You can review the source code yourself
- Runs as your local user (no privilege escalation)
- Only connects to localhost Obsidian API
- Web fetch blocks private/internal networks

## Troubleshooting

**Server won't start:**
- Verify Bun is installed: `bun --version`
- Check the API key is correct in the config
- Ensure Obsidian is running with Local REST API enabled

**Tools not available in Claude:**
- Check Claude Desktop logs (View → Toggle Developer → Show Logs)
- Verify the config file path and syntax
- Restart Claude Desktop after config changes

**API errors:**
- Verify Local REST API plugin is configured in Obsidian
- Check the API URL and port are correct
- Ensure your vault is accessible

## Project Structure

```
obsidian-mcp/
├── src/
│   ├── index.ts          # Entry point
│   ├── core/
│   │   └── server.ts     # MCP server implementation
│   ├── tools/
│   │   ├── local-rest-api.ts  # Obsidian API tools (consolidated to 5)
│   │   └── fetch.ts            # Web scraping tool
│   ├── shared/
│   │   ├── tool-registry.ts    # Tool registration system
│   │   └── tool-registry.test.ts  # Tests
├── .eslintrc.json        # ESLint configuration
├── .prettierrc.json      # Prettier configuration
├── package.json
├── tsconfig.json
└── README.md
```

## What's New

### v0.1.0
- Consolidated 15 tools into 6 more powerful tools
- Added timeout handling (30s default) for all API requests
- Fixed IP validation security bug (172.16-31 range)
- Added ESLint and Prettier configuration
- Added test suite with Bun
- Simplified tool descriptions for better AI understanding
- Added global Claude Code setup instructions

## References

- [MCP Specification](https://spec.modelcontextprotocol.io/)
- [Local REST API Plugin](https://github.com/coddingtonbear/obsidian-local-rest-api)
- [Claude Desktop](https://claude.ai/download)