MCP Apple Obsidian

A comprehensive Model Context Protocol (MCP) server for Obsidian on macOS. This server provides extensive tools for interacting with Obsidian vaults, notes, and application state through AppleScript, URI schemes, and direct file system access.

Features

Vault Management

• List vaults: Discover all Obsidian vaults on your Mac

• Get vault info: Detailed information about vault contents and structure

• Vault statistics: Comprehensive analytics including tag counts, link statistics, and more

Note Operations

• Read notes: Access full content of any note in markdown format

• Write notes: Create new notes or update existing ones

• Delete notes: Remove notes with optional backup

• Move notes: Rename or relocate notes within the vault

• List notes: Browse notes with filtering by folder and file type

• Note metadata: Extract tags, links, frontmatter, and word counts

Frontmatter / Properties

• Read properties: Get all frontmatter properties from a note

• Set property: Add or update a single property

• Set multiple properties: Batch update frontmatter

• Delete property: Remove a property from frontmatter

• Search by property: Find notes matching property values (equals, contains, gt, lt, exists)

Tag Management

• Get note tags: List all tags in a note (inline + frontmatter)

• Add tag: Add a tag to a note

• Remove tag: Remove a tag from a note

• Rename tag: Rename a tag within a note or across the entire vault

• Get all tags: List all unique tags with occurrence counts

Task Management

• Get tasks: List all tasks from a note with metadata (due dates, priority, tags)

• Add task: Create new tasks with optional due dates, priority, and tags

• Complete task: Mark tasks as done

• Uncomplete task: Mark completed tasks as incomplete

• Update task: Modify task description, due date, or priority

• Delete task: Remove tasks from notes

• Search tasks: Find tasks across vault by status, due date, tag, or description

Search & Discovery

• Full-text search: Search note content with regex support

• Tag search: Find notes by specific tags

• Backlink discovery: Find all notes linking to a specific note

• Property search: Find notes by frontmatter properties

• Folder browsing: Navigate vault structure

Obsidian Application Control

• Launch Obsidian: Start the app with optional vault selection

• Open notes: Bring specific notes to the foreground

• Create notes via URI: Use Obsidian's native note creation

• Daily notes: Open or create daily notes

• Search integration: Trigger Obsidian's search interface

• Focus control: Bring Obsidian to the front

• Active note detection: Get info about the currently open note

Installation

Quick Install (Recommended)

# Install via uvx (no permanent installation)
uvx mcp-apple-obsidian

# Or install via pip
pip install mcp-apple-obsidian

Prerequisites

• macOS with Obsidian installed

• Python 3.11 or higher

• uv package manager (recommended)

Install from Source

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

# Quick setup with Makefile
make setup

# Or manually
uv sync
uv pip install -e .

Configuration

Environment Variables

MCP Configuration

Add the server to your MCP configuration file (~/.kimi/mcp.json or Claude Desktop config):

{
  "mcpServers": {
    "apple-obsidian": {
      "command": "uvx",
      "args": ["--from", "/path/to/mcp-apple-obsidian", "mcp-apple-obsidian"],
      "env": {
        "OBSIDIAN_DEFAULT_VAULT": "My Vault"
      }
    }
  }
}

Or for local development:

{
  "mcpServers": {
    "apple-obsidian": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/mcp-apple-obsidian", "mcp-apple-obsidian"],
      "env": {
        "OBSIDIAN_DEFAULT_VAULT": "My Vault"
      }
    }
  }
}

Available Tools (42 Total)

All tool names are prefixed with obsidian_ for clear context.

Vault Tools (3)

Note Reading Tools (3)

Note Writing Tools (6)

Frontmatter/Property Tools (5)

Search Operators for Properties:

• equals - Exact match

• contains - Substring match

• gt - Greater than (numeric)

• lt - Less than (numeric)

• exists - Property exists (no value needed)

Tag Management Tools (7)

Task Management Tools (7)

Task Features:

• Supports - [ ] and * [ ] syntax

• Due dates: 📅 YYYY-MM-DD

• Priority: 🔼 high, 🔽 low (default: normal)

• Inline tags supported

Search Tools (2)

Obsidian App Control (9)

Usage Examples

Reading & Writing Notes

Read the content of my "Projects/Ideas" note from the "Personal" vault using obsidian_read_note.

Working with Properties

Set the "status" property to "in-progress" in the note "Project Alpha" using obsidian_set_property.

Find all notes where the "priority" property equals "high" using obsidian_search_by_property.

Tag Management

Add the tag "urgent" to all notes in the Work folder using obsidian_add_tag.

Rename tag "old-project" to "new-project" across the entire vault using obsidian_rename_tag_vault.

What are the most used tags in my vault? Use obsidian_list_all_tags.

Task Management

Add a task "Review quarterly report" due 2024-12-31 with high priority to my daily note using obsidian_add_task.

Find all incomplete tasks tagged with "work" using obsidian_search_tasks.

Mark the task "Email client" as complete in the Projects/Clients note using obsidian_complete_task.

Searching

Search for all notes containing "meeting" in the "Work" vault using obsidian_search_notes.

Find all notes with property "type" set to "project" and tag "active" using obsidian_search_by_property and obsidian_find_notes_by_tag.

Working with Obsidian

Open the daily note in Obsidian and bring it to the foreground using obsidian_open_daily_note and obsidian_focus_app.

Create a new note called "Meeting Notes 2024-01-15" in the Work/Meetings folder with tags: work, meeting, january using obsidian_create_note.

Finding Connections

Find all notes that link to "Project Alpha" and list their tags using obsidian_find_backlinks.

API Documentation

See API.md for comprehensive API documentation with detailed input/output schemas.

See API_SPEC.json for machine-readable JSON schema.

Deployment & Distribution

For Users

The easiest way to use this MCP server:

# Via uvx (no installation required)
uvx mcp-apple-obsidian

# Via pip
pip install mcp-apple-obsidian
mcp-apple-obsidian

For Developers

See DEPLOYMENT.md for comprehensive deployment options including:

• PyPI publication

• GitHub Releases

• Homebrew formula

• Docker image

• Local development setup

Quick Deploy

# Build and test
make build
make publish-test

# Release to PyPI
make release VERSION=0.1.0

Architecture

The server uses three primary methods to interact with Obsidian:

1. File System Access: Direct read/write to vault files for maximum control

2. AppleScript: Application control and window management

3. URI Schemes: Native Obsidian integration for opening notes and triggering actions

This multi-layered approach ensures robust functionality even when Obsidian isn't running, while providing rich integration when it is.

Development

Using the Makefile

This project includes a comprehensive Makefile for common tasks:

# Setup development environment
make setup

# Run tests
make test              # All tests
make test-unit         # Unit tests only
make test-coverage     # With coverage report

# Code quality
make lint              # Run linters
make format            # Format code
make check             # Run all checks (lint + test)
make fix               # Fix auto-fixable issues

# MCP Server installation
make install-claude    # Configure for Claude Desktop
make install-kimi      # Configure for Kimi CLI
make install-local     # Install for local testing

# Release
make build             # Build distribution
make publish-test      # Publish to TestPyPI
make publish           # Publish to PyPI
make release VERSION=0.1.0  # Full release workflow

# See all available targets
make help

Running Tests

# Using Makefile
make test

# Or directly
uv run pytest

Code Formatting

make format
# Or: uv run ruff format .

Running Locally

# With default vault
OBSIDIAN_DEFAULT_VAULT="My Vault" make run

# Or directly
OBSIDIAN_DEFAULT_VAULT="My Vault" uv run mcp-apple-obsidian

Testing with MCP Inspector

make inspector
# Or: npx @modelcontextprotocol/inspector uv run mcp-apple-obsidian

License

MIT License - See LICENSE file for details.

Contributing

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

Troubleshooting

Vault Not Found

If the server can't find your vault, you can:

1. Specify the full path to the vault

2. Set OBSIDIAN_DEFAULT_VAULT environment variable

3. Ensure the vault has been opened in Obsidian at least once

AppleScript Permissions

If AppleScript commands fail, ensure:

1. Obsidian is in /Applications

2. Terminal/IDE has accessibility permissions in System Preferences > Security & Privacy > Privacy > Accessibility

3. Obsidian is running or the app path is correct

Large Files

If reading large notes fails, increase OBSIDIAN_MAX_FILE_SIZE.

Task Format

This server supports standard Obsidian task syntax:

- [ ] Incomplete task
- [x] Completed task
- [ ] Task with due date 📅 2024-12-25
- [ ] High priority task 🔼
- [ ] Low priority task 🔽
- [ ] Task with #tag