Obsidian MCP Server

A lightweight Model Context Protocol (MCP) 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 v1.0 or higher
2. Obsidian with the Local REST API plugin installed
3. Claude Desktop (or any MCP-compatible client)

Installation

1. Install dependencies

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

{
  "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:

   mkdir -p ~/.config/claude
   

2. Create ~/.config/claude/mcp_config.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:

   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:

# 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

# 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 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
• Local REST API Plugin
• Claude Desktop