MCP server for Obsidian (TypeScript + Bun)

Obsidian MCP 服务（TypeScript + Bun）

一个模型上下文协议（MCP）服务，可让 Claude（或任何兼容 MCP 的大模型）通过 Local REST API 社区插件与 Obsidian 库交互。该服务使用 TypeScript 编写，可通过 bunx 运行。

---

✨ 组件

工具

工具名称	描述
obsidian_status	返回 Obsidian Local REST API 服务的基本详情和你的身份验证状态
obsidian_delete_active	删除 Obsidian 界面中当前处于活动状态的笔记
obsidian_get_active	获取活动笔记的完整内容（Markdown 或 JSON 视图）
obsidian_patch_active	相对于标题、块引用或 front-matter 字段，在活动笔记中插入、替换或前置内容
obsidian_post_active	在活动笔记末尾追加 Markdown
obsidian_put_active	替换活动笔记的整个正文
obsidian_get_commands	列出 Obsidian 命令面板中的所有可用命令
obsidian_execute_command	根据命令 ID 执行指定的 Obsidian 命令
obsidian_open_file	在 Obsidian 中打开指定文件（如果文件不存在则创建）；可选标志用于在新叶子中打开
obsidian_delete_periodic	删除指定周期当前的每日／每周／每月／每季度／每年笔记
obsidian_get_periodic	返回指定周期当前笔记的内容
obsidian_patch_periodic	相对于标题、块引用或 front-matter 字段，在周期笔记中插入／替换内容
obsidian_post_periodic	在周期笔记末尾追加 Markdown（如果笔记不存在则创建）
obsidian_put_periodic	替换周期笔记的整个正文
obsidian_search_dataview	在整个库中运行 Dataview-DQL 查询，并返回匹配的行
obsidian_search_json_logic	针对结构化笔记元数据运行 JsonLogic 查询
obsidian_simple_search	执行纯文本模糊搜索，可选择返回周边上下文
obsidian_list_vault_root	列出库根目录中的所有文件和目录
obsidian_list_vault_directory	列出库中指定文件夹内的文件和目录
obsidian_delete_file	删除库中的指定文件（或目录）
obsidian_get_file	获取库中文件的内容（Markdown 或 JSON 视图）
obsidian_patch_file	相对于标题、块引用或 front-matter 字段，在任意文件中插入／替换内容
obsidian_post_file	在文件末尾追加 Markdown（如果文件不存在则创建）
obsidian_put_file	创建新文件，或替换现有文件的整个正文

更多详情请参阅 Obsidian 的 Local REST API 规范。

---

示例提示词

# Summarize the latest “architecture call” note
# (Claude will transparently call list_files_in_vault → get_file_contents)
Get the contents of the last “architecture call” note and summarize them.

# Find all mentions of Cosmos DB
Search for all files where “Azure CosmosDb” is mentioned and explain the context briefly.

# Create a summary note
Summarize yesterday’s meeting and save it as “summaries/2025-04-24-meeting.md”. Add a short intro suitable for e-mail.

---

⚙️ 配置

Obsidian REST API 密钥

有两种方法可将 Obsidian API 密钥传递给服务：

1. 服务配置（推荐）——通过 Claude（或其他客户端）的 MCP 服务声明中的 env 字段传递：

// claude_desktop_config.json
{
  "mcpServers": {
    "@fazer-ai/mcp-obsidian": {
      "command": "bunx",
      "args": ["@fazer-ai/mcp-obsidian@latest"],
      "env": {
        "OBSIDIAN_API_KEY": "your-obsidian-api-key"
      }
    }
  }
}

说明

使用 @fazer-ai/mcp-obsidian@latest，确保始终运行最新版本的服务。

2. 也可以使用 .env 文件。将密钥放入上文创建的 .env 文件中。请注意，文件必须放在 MCP 服务运行所在的工作目录中。

环境变量

你可以参考 .env.example 文件来创建自己的 .env 文件。

OBSIDIAN_API_KEY=   # Obtain this from the plugin settings in Obsidian
OBSIDIAN_PROTOCOL=http
OBSIDIAN_HOST=localhost
OBSIDIAN_PORT=27123 # Port the Local REST API plugin is bound to

---

🛠 开发

在 Claude Desktop 上运行本地版本

克隆此仓库后，你可以更新 Claude 的配置，让它运行服务器的本地版本，而不是从 npm 拉取。 这有助于在发布之前快速测试更改。

说明

请注意，你对代码所做的任何更改都要在重启 Claude Desktop 应用后才会生效。

1. 克隆此仓库并运行 bun install 安装依赖项。
2. 更新 claude_desktop_config.json，使其指向服务器的本地版本：

// claude_desktop_config.json
{
  "mcpServers": {
    "@fazer-ai/mcp-obsidian": {
      "command": "bun",
      "args": ["/path/to/repo/src/index.ts"],
      "env": {
        "OBSIDIAN_API_KEY": "your-obsidian-api-key"
      }
    }
  }
}

重要

请注意，这里使用 bun 而不是 bunx。

调试

MCP 服务通过 stdio 通信，因此普通调试器并无帮助。
请使用 MCP Inspector：

npx @modelcontextprotocol/inspector bun /path/to/repo/src/index.ts

打开它打印出的 URL，即可逐步检查请求、查看工具调用并实时观察日志（通常为 http://localhost:6274）。

---

📦 发布

1. 更新 package.json 中的版本。
2. 创建 GitHub 发布版本。
3. 运行 bun publish。

---

许可证

MIT – 详见 LICENSE。