MCP Apple Obsidian

MCP苹果黑曜石

macOS上用于黑曜石的全面模型上下文协议（MCP）服务器。此服务器提供了广泛的工具，用于通过AppleScript、URI方案和直接文件系统访问与黑曜石保管库、笔记和应用程序状态进行交互。

特性

保险库管理

• 列出保管库：在Mac上发现所有黑曜石保险库
• 获取保险库信息：有关保险库内容和结构的详细信息
• 保险库统计信息：全面的分析，包括标签计数、链接统计等

注释操作

• 阅读笔记：以markdown格式访问任何笔记的全部内容
• 写笔记：创建新笔记或更新现有笔记
• 删除笔记：使用可选备份删除笔记
• 移动笔记：重命名或重新定位vault中的笔记
• 列出注释：按文件夹和文件类型筛选浏览笔记
• 注释元数据：提取标签、链接、封面和字数

前台/物业

• 读取属性：从笔记中获取所有frontmatter属性
• 设置属性：添加或更新单个属性
• 设置多个属性：批量更新frontmatter
• 删除属性：从frontmatter中删除属性
• 按房产搜索：查找与属性值匹配的注释（等于、包含、gt、lt、存在）

标签管理

• 获取笔记标签：在注释中列出所有标签（内联+frontmatter）
• 添加标记：在笔记中添加标签
• 移除标签：从笔记中删除标签
• 重命名标签：重命名注释内或整个vault中的标记
• 获取所有标签：列出所有具有出现次数的唯一标签

任务管理

• 获取任务：使用元数据（截止日期、优先级、标签）列出注释中的所有任务
• 添加任务：创建具有可选截止日期、优先级和标签的新任务
• 完成任务：将任务标记为已完成
• 任务未完成：将已完成的任务标记为未完成
• 更新任务：修改任务描述、截止日期或优先级
• 删除任务：从笔记中删除任务
• 搜索任务：按状态、截止日期、标记或描述在vault中查找任务

搜索与发现

• 全文搜索：使用正则表达式支持搜索笔记内容
• 标签搜索：按特定标签查找笔记
• 反向链接发现：查找链接到特定笔记的所有笔记
• 房产搜索：按frontmatter属性查找注释
• 文件夹浏览：浏览vault结构

黑曜石应用程序控制

• 发射黑曜石：使用可选的保险库选项启动应用程序
• 打开笔记：将特定笔记置于前台
• 通过URI创建笔记：使用黑曜石的原生音符创作
• 每日笔记：打开或创建每日笔记
• 搜索集成：触发黑曜石的搜索界面
• 聚焦控制：把黑曜石带到前线
• 主动纸币检测：获取当前打开的笔记的信息

安装

快速安装（推荐）

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

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

先决条件

• 安装了Obsidian的macOS
• Python 3.11或更高版本
• uv 包管理器（推荐）

从源代码安装

# 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 .

配置

环境变量

MCP配置

将服务器添加到MCP配置文件中(~/.kimi/mcp.json 或Claude桌面配置）：

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

或者为了当地发展：

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

可用工具（共42个）

所有工具名称前面都有前缀 obsidian_ 为了清晰的上下文。

保险库工具（3）

笔记阅读工具（3）

笔记书写工具（6）

首页/属性工具（5）

属性搜索运算符：

• equals -完全匹配
• contains -子字符串匹配
• gt -大于（数字）
• lt -小于（数字）
• exists -属性存在（不需要值）

标签管理工具（7）

任务管理工具（7）

任务特性：

• 支持 - [ ] 和 * [ ] 语法
• 到期日： 📅 YYYY-MM-DD
• 优先： 🔼 高， 🔽 低（默认值：正常）
• 支持内联标签

搜索工具（2）

黑曜石应用程序控制（9）

用法示例

阅读和写作笔记

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

与物业合作

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.

标签管理

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.

任务管理

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.

搜索

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.

与黑曜石合作

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.

查找连接

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

API文档

看 API毫米 以获取全面的API文档和详细的输入/输出模式。

看 API_SPEC.json公司 用于机器可读的JSON模式。

部署和分发

对于用户

使用此MCP服务器的最简单方法：

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

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

对于开发者

看 部署.md 全面的部署选项包括：

• PyPI出版物
• GitHub发布
• 自制配方
• Docker镜像
• 当地开发设置

快速部署

# Build and test
make build
make publish-test

# Release to PyPI
make release VERSION=0.1.0

建筑

服务器使用三种主要方法与黑曜石交互：

1. 文件系统访问：直接读/写vault文件以实现最大控制
2. AppleScript：应用程序控制和窗口管理
3. URI方案：原生黑曜石集成，用于打开笔记和触发动作

这种多层方法即使在Obsidian未运行时也能确保强大的功能，同时在运行时提供丰富的集成。

发展

使用Makefile

该项目包括一个用于常见任务的全面Makefile：

# 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

运行测试

# Using Makefile
make test

# Or directly
uv run pytest

代码格式化

make format
# Or: uv run ruff format .

本地运行

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

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

MCP检验员测试

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

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

贡献

欢迎投稿！请随时提交拉取请求。

故障排除

未找到保险库

如果服务器找不到您的保管库，您可以：

1. 指定vault的完整路径
2. 集 OBSIDIAN_DEFAULT_VAULT 环境变量
3. 确保金库在黑曜石中至少打开过一次

AppleScript权限

如果AppleScript命令失败，请确保：

1. 黑曜石在 /Applications
2. 终端/IDE在“系统首选项”>“安全与隐私”>“隐私”>可访问性中具有可访问性权限
3. 黑曜石正在运行或应用程序路径正确

大文件

如果阅读大额钞票失败，请增加 OBSIDIAN_MAX_FILE_SIZE.

任务格式

此服务器支持标准的黑曜石任务语法：

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