mcp-apple-obsidian
Provides comprehensive tools for managing Obsidian vaults and notes, including vault management, note operations, frontmatter/properties, tag management, task management, search, and Obsidian app control.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-apple-obsidian search for notes with tag #project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: Obsidian MCP
Installation
Quick Install (Recommended)
# Install via uvx (no permanent installation)
uvx mcp-apple-obsidian
# Or install via pip
pip install mcp-apple-obsidianPrerequisites
macOS with Obsidian installed
Python 3.11 or higher
uvpackage 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 |
| Default vault name to use | None |
| Path to Obsidian.app |
|
| AppleScript timeout (seconds) | 30 |
| URI execution timeout (seconds) | 10 |
| Maximum note size to read (bytes) | 10MB |
| Create backups before modifications | true |
| Directory for 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 |
| List all known Obsidian vaults |
| Get detailed vault information |
| Get comprehensive vault statistics |
Note Reading Tools (3)
Tool | Description |
| Read note content |
| List notes in a vault/folder |
| Get tags, links, frontmatter, word count |
Note Writing Tools (6)
Tool | Description |
| Create or overwrite notes |
| Create structured notes with frontmatter |
| Delete notes with backup |
| Move/rename notes |
| Append content to notes |
| Prepend content to notes |
Frontmatter/Property Tools (5)
Tool | Description |
| Get all frontmatter properties |
| Set a single property |
| Batch update properties (JSON) |
| Remove a property |
| Search notes by property value |
Search Operators for Properties:
equals- Exact matchcontains- Substring matchgt- Greater than (numeric)lt- Less than (numeric)exists- Property exists (no value needed)
Tag Management Tools (7)
Tool | Description |
| Get all tags from a note |
| Add a tag to a note |
| Remove a tag from a note |
| Rename a tag in one note |
| Rename a tag everywhere |
| List all tags with counts |
| Find notes with a specific tag |
Task Management Tools (7)
Tool | Description |
| Get all tasks from a note |
| Add a new task |
| Mark a task complete |
| Mark a task incomplete |
| Delete a task |
| Modify task properties |
| Search tasks across vault |
Task Features:
Supports
- [ ]and* [ ]syntaxDue dates:
📅 YYYY-MM-DDPriority:
🔼high,🔽low (default: normal)Inline tags supported
Search Tools (2)
Tool | Description |
| Full-text search with regex |
| Find notes linking to a note |
Obsidian App Control (9)
Tool | Description |
| Check if app is running |
| Launch the app |
| Open a note in UI |
| Create note via URI |
| Open daily note |
| Open search in app |
| Bring app to front |
| Get current note info |
| 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-obsidianFor 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.0Architecture
The server uses three primary methods to interact with Obsidian:
File System Access: Direct read/write to vault files for maximum control
AppleScript: Application control and window management
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 helpRunning Tests
# Using Makefile
make test
# Or directly
uv run pytestCode 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-obsidianTesting with MCP Inspector
make inspector
# Or: npx @modelcontextprotocol/inspector uv run mcp-apple-obsidianLicense
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:
Specify the full path to the vault
Set
OBSIDIAN_DEFAULT_VAULTenvironment variableEnsure the vault has been opened in Obsidian at least once
AppleScript Permissions
If AppleScript commands fail, ensure:
Obsidian is in
/ApplicationsTerminal/IDE has accessibility permissions in System Preferences > Security & Privacy > Privacy > Accessibility
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 #tagAvailable Tools
42 toolsobsidian_add_tagB
Add a tag to a note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
tag: Tag to add (without # prefix)
Returns:
Success message or error
Inputs: vault (required), path (required), tag (required). Returns: result
obsidian_add_taskB
Add a new task to a note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
description: Task description
completed: Whether the task is completed
due_date: Optional due date (YYYY-MM-DD format)
priority: Optional priority ("high", "normal", "low")
tags: Optional comma-separated list of tags
Returns:
Success message or error
Inputs: vault (required), path (required), description (required), completed, +3 more. Returns: result
obsidian_append_noteA
Append content to the end of an existing note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
content: Content to append
Returns:
Success message or error
Inputs: vault (required), path (required), content (required). Returns: result
obsidian_check_app_runningA
Check if the Obsidian application is currently running.
Returns:
"true" if running, "false" otherwise
Inputs: no named parameters. Returns: result
obsidian_complete_taskB
Mark a task as completed by matching its description.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
task_description_contains: Text to match in task description
Returns:
Success message or error
Inputs: vault (required), path (required), task_description_contains (required). Returns: result
obsidian_create_noteC
Create a new note with a structured template.
Args:
vault: Name or path of the vault
path: Path where the note should be created
title: Optional title (defaults to filename)
tags: Optional list of tags to add
content: Optional main content body
Returns:
Success message or error
Inputs: vault (required), path (required), title, tags, +1 more. Returns: result
obsidian_create_note_in_appC
Create a new note using Obsidian's URI scheme.
Args:
vault: Name or ID of the vault
name: Name for the new note
content: Optional initial content
silent: If true, don't open the note after creation
Returns:
Success message or error
Inputs: vault (required), name (required), content, silent. Returns: result
obsidian_delete_noteB
Delete a note from the vault.
Args:
vault: Name or path of the vault
path: Path to the note to delete
Returns:
Success message or error
Inputs: vault (required), path (required). Returns: result
obsidian_delete_propertyB
Delete a frontmatter property from a note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
property_name: Name of the property to delete
Returns:
Success message or error
Inputs: vault (required), path (required), property_name (required). Returns: result
obsidian_delete_taskB
Delete a task from a note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
task_description_contains: Text to match in task description
Returns:
Success message or error
Inputs: vault (required), path (required), task_description_contains (required). Returns: result
obsidian_find_backlinksB
Find all notes that link to a specific note.
Args:
vault: Name or path of the vault
note_path: Path to the target note (without .md extension)
Returns:
JSON array of notes that link to the target
Inputs: vault (required), note_path (required). Returns: result
obsidian_find_notes_by_tagA
Find all notes that contain a specific tag.
Args:
vault: Name or path of the vault
tag: Tag to search for (without the #)
Returns:
JSON array of matching notes
Inputs: vault (required), tag (required). Returns: result
obsidian_focus_appB
Bring Obsidian to the foreground (activate it).
Returns:
Success message or error
Inputs: no named parameters. Returns: result
obsidian_get_active_note_infoA
Get information about the currently active note in Obsidian.
Returns:
JSON with note info (title, vault) or error message
Inputs: no named parameters. Returns: result
obsidian_get_app_versionA
Get the version of the installed Obsidian application.
Returns:
Version string or error message
Inputs: no named parameters. Returns: result
obsidian_get_note_metadataB
Get metadata about a note including tags, links, word count, and frontmatter.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
Returns:
JSON with note metadata
Inputs: vault (required), path (required). Returns: result
obsidian_get_propertiesB
Get all frontmatter properties from a note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
Returns:
JSON with all properties
Inputs: vault (required), path (required). Returns: result
obsidian_get_tagsA
Get all tags from a note (both inline and frontmatter).
Args:
vault: Name or path of the vault
path: Path to the note within the vault
Returns:
JSON array of tags
Inputs: vault (required), path (required). Returns: result
obsidian_get_tasksA
Get all tasks from a note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
include_completed: Whether to include completed tasks
Returns:
JSON array of tasks
Inputs: vault (required), path (required), include_completed. Returns: result
obsidian_get_vault_infoA
Get detailed information about a specific vault.
Args:
vault: Name or path of the vault
Returns:
JSON with vault path, note count, and folder structure
Inputs: vault (required). Returns: result
obsidian_get_vault_statsA
Get comprehensive statistics about a vault.
Args:
vault: Name or path of the vault
Returns:
JSON with vault statistics including tag counts, link analysis
Inputs: vault (required). Returns: result
obsidian_launch_appC
Launch the Obsidian application, optionally opening a specific vault.
Args:
vault: Optional vault name to open on launch
Returns:
Success message or error
Inputs: vault. Returns: result
obsidian_list_all_tagsA
Get all unique tags across the vault with their occurrence counts.
Args:
vault: Name or path of the vault
Returns:
JSON object with tag counts
Inputs: vault (required). Returns: result
obsidian_list_notesA
List all notes in a vault or specific folder.
Args:
vault: Name or path of the vault
folder: Optional subfolder path to list (e.g., "Projects")
include_attachments: Whether to include non-markdown files
Returns:
JSON array of note information
Inputs: vault (required), folder, include_attachments. Returns: result
obsidian_list_vaultsA
List all known Obsidian vaults on this Mac.
Returns a JSON array of vault information including name, ID, and path.
Inputs: no named parameters. Returns: result
obsidian_move_noteC
Move or rename a note within the vault.
Args:
vault: Name or path of the vault
source_path: Current path of the note
dest_path: New path for the note
Returns:
Success message or error
Inputs: vault (required), source_path (required), dest_path (required). Returns: result
obsidian_open_daily_noteB
Open or create the daily note in Obsidian.
Args:
vault: Name or ID of the vault
Returns:
Success message or error
Inputs: vault (required). Returns: result
obsidian_open_note_in_appC
Open a specific note in the Obsidian application.
Args:
vault: Name or ID of the vault
file: Path to the note within the vault
Returns:
Success message or error
Inputs: vault (required), file (required). Returns: result
obsidian_open_search_in_appB
Open search in Obsidian with a query.
Args:
vault: Name or ID of the vault
query: Search query to execute
Returns:
Success message or error
Inputs: vault (required), query (required). Returns: result
obsidian_prepend_noteB
Prepend content to the beginning of an existing note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
content: Content to prepend
Returns:
Success message or error
Inputs: vault (required), path (required), content (required). Returns: result
obsidian_read_noteA
Read the contents of a specific note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault (e.g., "Folder/Note Name")
Returns:
The full content of the note as markdown text
Inputs: vault (required), path (required). Returns: result
obsidian_remove_tagB
Remove a tag from a note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
tag: Tag to remove (without # prefix)
Returns:
Success message or error
Inputs: vault (required), path (required), tag (required). Returns: result
obsidian_rename_tag_in_noteB
Rename a tag within a single note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
old_tag: Current tag name (without #)
new_tag: New tag name (without #)
Returns:
Success message or error
Inputs: vault (required), path (required), old_tag (required), new_tag (required). Returns: result
obsidian_rename_tag_vaultA
Rename a tag across all notes in the vault.
Args:
vault: Name or path of the vault
old_tag: Current tag name (without #)
new_tag: New tag name (without #)
Returns:
JSON with count of updated notes
Inputs: vault (required), old_tag (required), new_tag (required). Returns: result
obsidian_search_by_propertyA
Search notes by frontmatter property value.
Args:
vault: Name or path of the vault
property_name: Name of the property to search
property_value: Value to search for (optional for "exists" operator)
operator: Comparison operator ("equals", "contains", "gt", "lt", "exists")
Returns:
JSON array of matching notes
Inputs: vault (required), property_name (required), property_value, operator. Returns: result
obsidian_search_notesA
Search for notes containing specific text or matching a pattern.
Args:
vault: Name or path of the vault
query: Search query (supports regex patterns)
case_sensitive: Whether search is case sensitive
search_content: Whether to search in file content (not just names)
Returns:
JSON array of matching notes with context
Inputs: vault (required), query (required), case_sensitive, search_content. Returns: result
obsidian_search_tasksA
Search for tasks across the vault.
Args:
vault: Name or path of the vault
status: Task status filter ("all", "completed", "incomplete")
tag: Optional tag to filter by
due_before: Filter tasks due before this date (YYYY-MM-DD)
due_after: Filter tasks due after this date (YYYY-MM-DD)
description_contains: Search text in task descriptions
Returns:
JSON array of matching tasks
Inputs: vault (required), status, tag, due_before, +2 more. Returns: result
obsidian_set_propertiesB
Set multiple frontmatter properties on a note at once.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
properties: JSON object with properties to set
Returns:
Success message or error
Inputs: vault (required), path (required), properties (required). Returns: result
obsidian_set_propertyC
Set a frontmatter property on a note.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
property_name: Name of the property to set
property_value: Value to set (will be parsed as YAML)
Returns:
Success message or error
Inputs: vault (required), path (required), property_name (required), property_value (required). Returns: result
obsidian_uncomplete_taskC
Mark a completed task as incomplete.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
task_description_contains: Text to match in task description
Returns:
Success message or error
Inputs: vault (required), path (required), task_description_contains (required). Returns: result
obsidian_update_taskC
Update a task's properties.
Args:
vault: Name or path of the vault
path: Path to the note within the vault
task_description_contains: Text to match in current description
new_description: New description text (optional)
new_due_date: New due date (YYYY-MM-DD, or "remove" to clear)
new_priority: New priority ("high", "normal", "low", or "remove")
Returns:
Success message or error
Inputs: vault (required), path (required), task_description_contains (required), new_description, +2 more. Returns: result
obsidian_write_noteB
Create a new note or overwrite an existing one.
Args:
vault: Name or path of the vault
path: Path where the note should be created (e.g., "Folder/Note Name")
content: The markdown content to write
append: If true, append to existing content instead of overwriting
Returns:
Success message or error
Inputs: vault (required), path (required), content (required), append. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 42 tools
Most tools have distinct purposes (e.g., add_tag vs remove_tag), but there is some overlap with note creation (create_note, create_note_in_app, write_note) and task operations (add_task, update_task). Descriptions help differentiate, but the sheer number of tools can cause confusion.
All tools follow a consistent 'obsidian_verb_noun' pattern with clear verbs (e.g., add, get, search, delete). Naming is uniform and predictable, aiding agent understanding.
42 tools is high for a single server, covering many aspects of Obsidian. While comprehensive, it may be overwhelming and could be streamlined. The scope justifies the count, but it exceeds typical optimal ranges.
The tool surface is very thorough, covering note CRUD, tasks, tags, properties, vault management, search, and app control. Only minor gaps (e.g., moving tasks) exist, making it highly complete for Obsidian automation.
Maintenance
Related MCP Connectors
Hosted MCP server for Obsidian Sync vaults: read, search, edit notes. Not affiliated with Obsidian.
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Search, read, and write your Apple Notes from ChatGPT/Claude via a local Mac agent + MCP relay.
Remote MCP server for notes, tasks, kanban boards and docs - the Slates agentic workspace
Related MCP Servers
- AlicenseAqualityDmaintenanceThis project implements a Model Context Protocol (MCP) server for connecting AI models with Obsidian knowledge bases. Through this server, AI models can directly access and manipulate Obsidian notes, including reading, creating, updating, and deleting notes, as well as managing folder structures.1167 npm311MIT
- AlicenseBqualityFmaintenanceA Model Context Protocol server that enables AI assistants to read, write, and manipulate notes in your Obsidian vault through a standardized interface.54ISC
- AlicenseAqualityFmaintenanceA Model Context Protocol (MCP) server that provides AI assistants with secure access to Obsidian vaults. Enables reading, writing, searching, and managing notes without requiring Obsidian to be running.507,721 npmApache 2.0
- FlicenseNot gradedqualityCmaintenanceMCP server that provides tools and resources for AI models to interact with an Obsidian vault, enabling file operations, search, and management via the Model Context Protocol.2-