<p align="center"> <img src="images/banner.png" alt="MCP Apple Obsidian banner" /> </p>

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

Variable	Description	Default
OBSIDIAN_DEFAULT_VAULT	Default vault name to use	None
OBSIDIAN_APP_PATH	Path to Obsidian.app	/Applications/Obsidian.app
OBSIDIAN_APPLESCRIPT_TIMEOUT	AppleScript timeout (seconds)	30
OBSIDIAN_URI_TIMEOUT	URI execution timeout (seconds)	10
OBSIDIAN_MAX_FILE_SIZE	Maximum note size to read (bytes)	10MB
OBSIDIAN_CREATE_BACKUPS	Create backups before modifications	true
OBSIDIAN_BACKUP_DIR	Directory for backups	~/.obsidian-mcp-backups

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)

Tool	Description
obsidian_list_vaults	List all known Obsidian vaults
obsidian_get_vault_info	Get detailed vault information
obsidian_get_vault_stats	Get comprehensive vault statistics

Note Reading Tools (3)

Tool	Description
obsidian_read_note	Read note content
obsidian_list_notes	List notes in a vault/folder
obsidian_get_note_metadata	Get tags, links, frontmatter, word count

Note Writing Tools (6)

Tool	Description
obsidian_write_note	Create or overwrite notes
obsidian_create_note	Create structured notes with frontmatter
obsidian_delete_note	Delete notes with backup
obsidian_move_note	Move/rename notes
obsidian_append_note	Append content to notes
obsidian_prepend_note	Prepend content to notes

Frontmatter/Property Tools (5)

Tool	Description
obsidian_get_properties	Get all frontmatter properties
obsidian_set_property	Set a single property
obsidian_set_properties	Batch update properties (JSON)
obsidian_delete_property	Remove a property
obsidian_search_by_property	Search notes by property value

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)

Tool	Description
obsidian_get_tags	Get all tags from a note
obsidian_add_tag	Add a tag to a note
obsidian_remove_tag	Remove a tag from a note
obsidian_rename_tag_in_note	Rename a tag in one note
obsidian_rename_tag_vault	Rename a tag everywhere
obsidian_list_all_tags	List all tags with counts
obsidian_find_notes_by_tag	Find notes with a specific tag

Task Management Tools (7)

Tool	Description
obsidian_get_tasks	Get all tasks from a note
obsidian_add_task	Add a new task
obsidian_complete_task	Mark a task complete
obsidian_uncomplete_task	Mark a task incomplete
obsidian_delete_task	Delete a task
obsidian_update_task	Modify task properties
obsidian_search_tasks	Search tasks across vault

Task Features:

• Supports - [ ] and * [ ] syntax
• Due dates: 📅 YYYY-MM-DD
• Priority: 🔼 high, 🔽 low (default: normal)
• Inline tags supported

Search Tools (2)

Tool	Description
obsidian_search_notes	Full-text search with regex
obsidian_find_backlinks	Find notes linking to a note

Obsidian App Control (9)

Tool	Description
obsidian_check_app_running	Check if app is running
obsidian_launch_app	Launch the app
obsidian_open_note_in_app	Open a note in UI
obsidian_create_note_in_app	Create note via URI
obsidian_open_daily_note	Open daily note
obsidian_open_search_in_app	Open search in app
obsidian_focus_app	Bring app to front
obsidian_get_active_note_info	Get current note info
obsidian_get_app_version	Get Obsidian version

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