# 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
