npm package: @hu14/obsidian-mcp
Description: MCP server for Obsidian Local REST API - Connect Claude and other AI assistants to your Obsidian vault
Author: hu
Latest version: 1.0.0

# @hu14/obsidian-mcp

[![npm version](https://badge.fury.io/js/@hu14%2Fobsidian-mcp.svg)](https://www.npmjs.com/package/@hu14/obsidian-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

> A Model Context Protocol (MCP) server that connects Claude and other AI assistants to your Obsidian vault via the Local REST API plugin.

## Overview

`@hu14/obsidian-mcp` enables AI assistants to:

- 📖 **Read and search** your notes with full-text or structured queries
- ✍️ **Create and edit** notes programmatically
- 🏷️ **Manage tags** and explore your vault structure
- 📅 **Work with periodic notes** (daily, weekly, monthly)
- 🎯 **Execute Obsidian commands** to control the UI
- 📂 **Interact with the active file** currently open in Obsidian

## Prerequisites

Before using this package, you need:

1. **Obsidian** installed on your computer
2. **Local REST API** plugin installed and enabled:
   - Open Obsidian Settings → Community Plugins
   - Search for "Local REST API" and install it
   - Enable the plugin
   - Copy your API key from the plugin settings

## Installation

### Global Installation (Recommended)

```bash
npm install -g @hu14/obsidian-mcp
```

### Local Installation

```bash
npm install @hu14/obsidian-mcp
```

## Configuration

### Environment Variables

Set the following environment variables:

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `OBSIDIAN_API_KEY` | ✅ Yes | - | Your API key from Local REST API settings |
| `OBSIDIAN_HOST` | ❌ No | `127.0.0.1` | Obsidian server host |
| `OBSIDIAN_PORT` | ❌ No | `27124` | HTTPS port (or `27123` for HTTP) |
| `OBSIDIAN_PROTOCOL` | ❌ No | `https` | Protocol: `https` or `http` |

### Example Configuration

```bash
# Linux/macOS
export OBSIDIAN_API_KEY="your_api_key_here"

# Windows (PowerShell)
$env:OBSIDIAN_API_KEY="your_api_key_here"

# Windows (CMD)
set OBSIDIAN_API_KEY=your_api_key_here
```

## Usage

### Standalone Usage

After global installation:

```bash
# stdio mode (default, for MCP clients)
obsidian-mcp

# HTTP mode
obsidian-mcp --http --port=3000
```

### With Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "@hu14/obsidian-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

Or with a local installation:

```json
{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["./node_modules/@hu14/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

## Available Tools

The server exposes **25 tools** organized by category:

### 📁 Vault Operations

| Tool | Description |
|------|-------------|
| `vault_list` | List files and directories in a vault path |
| `vault_get` | Read a file's content (markdown, JSON, or document map) |
| `vault_create` | Create a new file or overwrite an existing one |
| `vault_update` | Replace the content of an existing file |
| `vault_delete` | Delete a file from the vault |
| `vault_append` | Append content to the end of a file |
| `vault_patch` | Partially update content relative to a heading, block, or frontmatter field |

### 🔍 Search

| Tool | Description |
|------|-------------|
| `search_simple` | Full-text search with context snippets |
| `search_dataview` | Query using Dataview DQL (requires Dataview plugin) |
| `search_jsonlogic` | Advanced queries using JsonLogic |

### ⚡ Commands

| Tool | Description |
|------|-------------|
| `command_list` | List all available Obsidian commands |
| `command_execute` | Execute a command by its ID |

### 🏷️ Tags

| Tool | Description |
|------|-------------|
| `tags_list` | Get all tags in the vault with usage counts |

### 📅 Periodic Notes

| Tool | Description |
|------|-------------|
| `periodic_get` | Get the current periodic note (daily/weekly/monthly/quarterly/yearly) |
| `periodic_create` | Create or update a periodic note |
| `periodic_delete` | Delete a periodic note |
| `periodic_append` | Append content to a periodic note |
| `periodic_patch` | Partially update a periodic note |

### 📝 Active File

| Tool | Description |
|------|-------------|
| `active_get` | Get the content of the currently active/open file |
| `active_update` | Replace the content of the active file |
| `active_delete` | Delete the currently active file |
| `active_append` | Append content to the active file |
| `active_patch` | Partially update the active file |
| `active_open` | Open a specific file in the Obsidian UI |

## Example Interactions

Here are examples of how you might interact with your vault through an AI assistant:

### Reading Notes
```
"Show me my note about Project X"
→ Uses vault_get with path="Projects/Project X.md"

"What tags do I have in my vault?"
→ Uses tags_list
```

### Searching
```
"Find all notes containing 'machine learning'"
→ Uses search_simple with query="machine learning"

"Show me tasks tagged with #urgent"
→ Uses search_dataview with DQL query
```

### Creating Content
```
"Create a new daily note for today"
→ Uses periodic_create with period="daily"

"Add a task to my active note"
→ Uses active_append with content="- [ ] New task"
```

### Managing the UI
```
"Open my Projects folder"
→ Uses active_open with filename="Projects"

"Run the command to insert a template"
→ Uses command_execute with the appropriate command ID
```

## Troubleshooting

### Connection Issues

1. **Verify Obsidian is running** with the Local REST API plugin enabled
2. **Check your API key** is correctly set in the environment variable
3. **Verify the port** - Default HTTPS port is `27124`, HTTP is `27123`
4. **Check protocol** - Use `https` by default, or `http` if you've disabled HTTPS in the plugin settings

### Certificate Errors

The package automatically handles self-signed certificates from the Local REST API plugin. If you encounter certificate issues, ensure you're using HTTPS with the default configuration.

## Changelog

See [CHANGELOG.md](./CHANGELOG.md) for version history.

## License

MIT © hu

## Acknowledgments

- [Obsidian](https://obsidian.md/) - The note-taking app that powers this
- [Local REST API Plugin](https://github.com/coddingtonbear/obsidian-local-rest-api) - The Obsidian plugin that enables API access
- [Model Context Protocol](https://modelcontextprotocol.io/) - The protocol that makes this integration possible