obsidian-notes-mcp

The best MCP server for Obsidian. Connect Claude Code and Claude Desktop to your notes with one-line setup.

Why obsidian-mcp?

| Feature | obsidian-mcp | Others | |---------|-------------|--------| | Setup | One line | Complex config | | Token usage | 90%+ reduction | Full content always | | Tools | 18 comprehensive | 5-8 basic | | Speed | < 1 second | 3+ minutes (some) | | Periodic notes | Daily, Weekly, Monthly | Daily only |

Features

• One-line setup - Works with Claude Code and Claude Desktop
• 18 powerful tools - Full CRUD, search, periodic notes, batch operations
• Token-efficient - Smart responses minimize token usage by 90%+
• Blazing fast - Local search completes in < 1 second
• Bun-powered - 4x faster startup than Node.js

Quick Start

1. Install Obsidian Local REST API Plugin

1. Open Obsidian
2. Go to Settings → Community Plugins → Browse
3. Search for "Local REST API"
4. Install and enable it
5. Copy your API key from the plugin settings

2. Add to Claude Code (One Line!)

claude mcp add obsidian -e OBSIDIAN_API_KEY=your_key_here -e OBSIDIAN_REJECT_UNAUTHORIZED=false -- npx -y obsidian-notes-mcp

Note: The OBSIDIAN_REJECT_UNAUTHORIZED=false is required because Obsidian's Local REST API uses a self-signed HTTPS certificate.

Done! Claude can now access your Obsidian vault.

Alternative: Claude Desktop

Add to your Claude Desktop config:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/claude/claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-notes-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "your_key_here",
        "OBSIDIAN_REJECT_UNAUTHORIZED": "false"
      }
    }
  }
}

Available Tools (18 Total)

Note Management (5 tools)

| Tool | Description | Example | |------|-------------|---------| | list_notes | List notes with pagination | "List my notes in the Projects folder" | | read_note | Read note content | "Read my meeting notes from today" | | create_note | Create new note with frontmatter | "Create a note called 'Project Ideas'" | | update_note | Append, prepend, or replace content | "Add this to my daily note" | | delete_note | Delete note (requires confirmation) | "Delete the old draft note" |

Search (3 tools)

| Tool | Description | Example | |------|-------------|---------| | search | Fast full-text search | "Search for notes about Python" | | search_tags | Find notes by tags | "Find all notes tagged #project" | | search_frontmatter | Search by frontmatter fields | "Find notes with status: draft" |

Periodic Notes (4 tools)

| Tool | Description | Example | |------|-------------|---------| | daily_note | Get/create today's daily note | "Show me today's daily note" | | weekly_note | Get/create weekly note | "What's in this week's note?" | | monthly_note | Get/create monthly note | "Create January's monthly review" | | append_to_daily | Append to daily note | "Add 'Had meeting with team' to today" |

Batch Operations (3 tools)

| Tool | Description | Example | |------|-------------|---------| | batch_read | Read multiple notes at once | "Read all my project notes" | | batch_create | Create multiple notes at once | "Create these 5 meeting notes" | | vault_stats | Get vault statistics | "How many notes do I have?" |

Commands (3 tools)

| Tool | Description | Example | |------|-------------|---------| | list_commands | List Obsidian commands | "What commands are available?" | | execute_command | Run any Obsidian command | "Open the graph view" | | get_active_note | Get currently open note | "What note do I have open?" |

Architecture

┌─────────────────────────────────────────────────────────────┐
│                  Claude Code / Desktop                       │
└───────────────────────────┬─────────────────────────────────┘
                            │ MCP Protocol (stdio)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│                    obsidian-mcp Server                       │
│  ┌───────────────────────────────────────────────────────┐  │
│  │                   18 MCP Tools                         │  │
│  │  Notes: list, read, create, update, delete            │  │
│  │  Search: text, tags, frontmatter                      │  │
│  │  Periodic: daily, weekly, monthly                     │  │
│  │  Batch: read, create, stats                           │  │
│  │  Commands: list, execute, active                      │  │
│  └───────────────────────────────────────────────────────┘  │
│  ┌───────────────────────────────────────────────────────┐  │
│  │            Token Optimization Layer                    │  │
│  │  • Pagination (20 items default)                      │  │
│  │  • Truncation (5000 chars default)                    │  │
│  │  • Smart summaries                                    │  │
│  └───────────────────────────────────────────────────────┘  │
└───────────────────────────┬─────────────────────────────────┘
                            │ HTTPS (localhost:27124)
                            ▼
┌─────────────────────────────────────────────────────────────┐
│              Obsidian + Local REST API Plugin                │
└─────────────────────────────────────────────────────────────┘

Configuration

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | OBSIDIAN_API_KEY | Yes | - | API key from Local REST API plugin | | OBSIDIAN_HOST | No | 127.0.0.1 | Obsidian host address | | OBSIDIAN_PORT | No | 27124 | Obsidian port | | OBSIDIAN_PROTOCOL | No | https | http or https | | OBSIDIAN_REJECT_UNAUTHORIZED | No | true | Set "false" for self-signed certs |

Token Efficiency

This MCP is designed to minimize token usage:

| Operation | Without Optimization | With obsidian-mcp | Savings | |-----------|---------------------|-------------------|---------| | List 1000 notes | ~100,000 tokens | ~2,000 tokens | 98% | | Read 10 notes | ~50,000 tokens | ~5,000 tokens | 90% | | Search vault | ~200,000 tokens | ~3,000 tokens | 98% |

How it works:

• Pagination - Returns 20 items per page by default
• Truncation - Limits content to 5000 characters
• Smart summaries - Returns paths and metadata, not full content
• Batch operations - Reduces API round-trips

Examples

Create a note with frontmatter

"Create a note called 'Meeting Notes' in the Work folder with tags project and meeting"

Search and summarize

"Search my notes for 'machine learning' and summarize what I've written"

Daily journaling

"Add to today's daily note: Had a productive meeting about the new feature"

Batch operations

"Read all notes in my Projects folder and give me an overview"

Development

# Clone the repository
git clone https://github.com/krisk248/obsidian-mcp.git
cd obsidian-mcp

# Install dependencies
bun install

# Run in development mode
bun run dev

# Run tests
bun test

# Build for production
bun run build

Requirements

• Obsidian with Local REST API plugin
• Node.js 20+ or Bun

Troubleshooting

"Cannot connect to Obsidian"

1. Make sure Obsidian is running
2. Verify Local REST API plugin is enabled
3. Check the API key is correct

"Self-signed certificate error" or "Unknown error"

The Obsidian Local REST API uses HTTPS with a self-signed certificate. Make sure you included the environment variable in your setup:

# For Claude Code
claude mcp add obsidian -e OBSIDIAN_API_KEY=your_key -e OBSIDIAN_REJECT_UNAUTHORIZED=false -- npx -y obsidian-notes-mcp

# Or set it manually
OBSIDIAN_REJECT_UNAUTHORIZED=false

Search is slow

This MCP uses fast local search (< 1 second). If you experience slowness, ensure you're using the latest version.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see LICENSE for details.

Credits

• Built with Model Context Protocol SDK
• Powered by Bun
• Integrates with Obsidian Local REST API