@hu14/obsidian-mcp

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)

npm install -g @hu14/obsidian-mcp

Local Installation

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

# 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:

# 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:

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

Or with a local installation:

{
  "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 for version history.

License

MIT © hu

Acknowledgments

• Obsidian - The note-taking app that powers this
• Local REST API Plugin - The Obsidian plugin that enables API access
• Model Context Protocol - The protocol that makes this integration possible