如何设置 Obsidian MCP Server (2026)

如何设置 Obsidian MCP 服务器 (2026)

Obsidian 是最受欢迎的知识管理工具之一，数百万用户在本地 Markdown 文件中存储笔记、研究资料和个人维基。通过 MCP（模型上下文协议/Model Context Protocol），你可以将你的 Obsidian 库直接连接到 Claude 等 AI 助手，让它们读取你的笔记、在库中进行搜索、创建新笔记，并结合你的知识库上下文进行工作。

本指南将向你展示如何设置 Obsidian MCP 服务器并将其连接到 Claude Desktop、Cursor 或任何兼容 MCP 的客户端。

为什么通过 MCP 将 Obsidian 连接到 AI？

如果没有 MCP，在 Obsidian 笔记中使用 AI 意味着需要手动将内容复制并粘贴到聊天窗口。有了 MCP，AI 可以：

• 搜索整个库：通过关键词、标签或内容进行搜索
• 读取特定笔记：理解其上下文，包括维基链接（wiki links）和反向链接（backlinks）
• 创建新笔记：基于对话或研究内容生成笔记
• 更新现有笔记：补充新信息
• 分析关联：利用你的链接图谱分析笔记间的联系
• 生成摘要：从多个相关的笔记中提取汇总

AI 能够直接访问你的知识库，而不是处理断开连接的片段。

前提条件

要求	详情
Obsidian	任何近期版本（库本质上就是一个存放 Markdown 文件的文件夹）
Node.js	v18 或更高版本
MCP 客户端	Claude Desktop, Cursor, VS Code 等
npm	用于安装 MCP 服务器

方案 1：使用 Obsidian MCP Server 软件包

由社区维护的 obsidian-mcp-server 软件包为 Obsidian 库提供了一个开箱即用的 MCP 服务器。

第 1 步：安装服务器

npm install -g obsidian-mcp-server

第 2 步：配置 Claude Desktop

将服务器添加到你的 Claude Desktop 配置中。

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": [
        "obsidian-mcp-server",
        "--vault",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}

请将路径替换为你 Obsidian 库文件夹的实际路径。

第 3 步：重启 Claude Desktop

关闭并重新打开 Claude Desktop。你应该能在工具面板中看到列出的 Obsidian MCP 服务器。

第 4 步：测试连接

让 Claude 与你的库进行交互：

在我的 Obsidian 库中搜索关于 "machine learning" 的笔记

读取我库中名为 "Project Ideas" 的笔记

在我的库中创建一个名为 "Meeting Notes 2026-02-06" 的新笔记，并附上我们讨论内容的摘要

方案 2：使用 Filesystem MCP Server

如果你想要一个更简单的设置而不需要专用的 Obsidian 软件包，官方的 filesystem MCP 服务器可以直接处理 Obsidian 库，因为它们只是 Markdown 文件的文件夹。

第 1 步：配置 Filesystem 服务器

{
  "mcpServers": {
    "obsidian-vault": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}

第 2 步：使用它

Filesystem 服务器赋予 AI 对库目录中所有文件的读写权限。它可以：

• 列出所有笔记和文件夹
• 读取任何笔记的内容
• 创建新的 Markdown 文件
• 编辑现有文件
• 搜索文件名

与专用 Obsidian MCP 服务器相比，缺点是 filesystem 服务器无法理解 Obsidian 特有的功能，如维基链接 ([[note]])、标签、Frontmatter 或反向链接图谱。

方案 3：构建自定义 Obsidian MCP 服务器

为了获得最大的控制权，你可以根据自己的库结构构建自定义 MCP 服务器。以下是一个使用 TypeScript 的极简实现：

第 1 步：设置项目

mkdir obsidian-mcp
cd obsidian-mcp
npm init -y
npm install @modelcontextprotocol/sdk zod glob
npm install -D typescript @types/node tsx

第 2 步：编写服务器

创建 src/index.ts：

#!/usr/bin/env node

import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
import { z } from "zod";
import * as fs from "fs/promises";
import * as path from "path";
import { glob } from "glob";

const VAULT_PATH = process.argv[2] || process.env.OBSIDIAN_VAULT_PATH;

if (!VAULT_PATH) {
  console.error("Usage: obsidian-mcp <vault-path>");
  process.exit(1);
}

const server = new McpServer({
  name: "obsidian-vault",
  version: "1.0.0",
});

// 工具：按内容搜索笔记
server.tool(
  "search_notes",
  "Search Obsidian vault notes by content or title",
  {
    query: z.string().describe("Search query (searches titles and content)"),
    limit: z.number().optional().default(10).describe("Max results to return"),
  },
  async ({ query, limit }) => {
    const files = await glob("**/*.md", { cwd: VAULT_PATH });
    const results: { file: string; matches: string[] }[] = [];
    const queryLower = query.toLowerCase();

    for (const file of files) {
      const content = await fs.readFile(
        path.join(VAULT_PATH, file),
        "utf-8"
      );
      const titleMatch = file.toLowerCase().includes(queryLower);
      const lines = content.split("\n");
      const matchingLines = lines.filter((line) =>
        line.toLowerCase().includes(queryLower)
      );

      if (titleMatch || matchingLines.length > 0) {
        results.push({
          file,
          matches: matchingLines.slice(0, 3),
        });
      }

      if (results.length >= limit) break;
    }

    const output = results
      .map(
        (r) =>
          `**${r.file}**\n${r.matches.map((m) => `  > ${m.trim()}`).join("\n")}`
      )
      .join("\n\n");

    return {
      content: [
        {
          type: "text",
          text: results.length > 0 ? output : "No notes found matching your query.",
        },
      ],
    };
  }
);

// 工具：读取特定笔记
server.tool(
  "read_note",
  "Read the full content of an Obsidian note",
  {
    notePath: z
      .string()
      .describe("Path to the note relative to vault root (e.g., 'Projects/my-project.md')"),
  },
  async ({ notePath }) => {
    try {
      const fullPath = path.join(VAULT_PATH, notePath);
      const content = await fs.readFile(fullPath, "utf-8");
      return {
        content: [{ type: "text", text: content }],
      };
    } catch {
      return {
        content: [{ type: "text", text: `Note not found: ${notePath}` }],
        isError: true,
      };
    }
  }
);

// 工具：创建新笔记
server.tool(
  "create_note",
  "Create a new note in the Obsidian vault",
  {
    notePath: z
      .string()
      .describe("Path for the new note (e.g., 'Daily/2026-02-06.md')"),
    content: z.string().describe("Markdown content for the note"),
  },
  async ({ notePath, content }) => {
    const fullPath = path.join(VAULT_PATH, notePath);
    const dir = path.dirname(fullPath);

    await fs.mkdir(dir, { recursive: true });
    await fs.writeFile(fullPath, content, "utf-8");

    return {
      content: [{ type: "text", text: `Created note: ${notePath}` }],
    };
  }
);

// 工具：列出文件夹中的笔记
server.tool(
  "list_notes",
  "List all notes in a vault folder",
  {
    folder: z
      .string()
      .optional()
      .default("")
      .describe("Folder path relative to vault root (empty for root)"),
  },
  async ({ folder }) => {
    const searchPath = path.join(VAULT_PATH, folder);
    const files = await glob("**/*.md", { cwd: searchPath });

    return {
      content: [
        {
          type: "text",
          text:
            files.length > 0
              ? files.map((f) => `- ${f}`).join("\n")
              : "No notes found in this folder.",
        },
      ],
    };
  }
);

// 工具：获取笔记中的标签
server.tool(
  "get_tags",
  "Extract all tags from a note or the entire vault",
  {
    notePath: z
      .string()
      .optional()
      .describe("Specific note to get tags from (omit for all vault tags)"),
  },
  async ({ notePath }) => {
    const files = notePath
      ? [notePath]
      : await glob("**/*.md", { cwd: VAULT_PATH });

    const tagSet = new Set<string>();

    for (const file of files) {
      const content = await fs.readFile(
        path.join(VAULT_PATH, file),
        "utf-8"
      );
      const tags = content.match(/#[\w\-\/]+/g);
      if (tags) {
        tags.forEach((tag) => tagSet.add(tag));
      }
    }

    const sorted = Array.from(tagSet).sort();

    return {
      content: [
        {
          type: "text",
          text:
            sorted.length > 0
              ? sorted.join("\n")
              : "No tags found.",
        },
      ],
    };
  }
);

// 启动服务器
async function main() {
  const transport = new StdioServerTransport();
  await server.connect(transport);
  console.error(`Obsidian MCP server running for vault: ${VAULT_PATH}`);
}

main().catch((error) => {
  console.error("Fatal error:", error);
  process.exit(1);
});

第 3 步：构建并连接

# 在 package.json 中添加
# "type": "module"
# "scripts": { "build": "tsc", "dev": "tsx src/index.ts" }

npx tsc

# 测试
echo '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}' | node dist/index.js /path/to/your/vault

添加到 Claude Desktop 配置：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": [
        "/path/to/obsidian-mcp/dist/index.js",
        "/Users/yourname/Documents/MyVault"
      ]
    }
  }
}

实际应用案例

研究助手

在我的库中搜索所有关于 "transformer architecture" 的笔记，
并创建一个总结笔记，汇集所有匹配笔记中的关键见解。

每日笔记创建

在我的 Daily 文件夹中为今天（2026-02-06）创建一个新的每日笔记。
包含一个任务部分、一个会议笔记部分，并将其链接到昨天的每日笔记。

知识缺口分析

列出我库中所有的标签，并找出笔记数量少于 3 条的主题。
这些是我应该研究的潜在知识缺口。

笔记重构

读取我的 "Machine Learning" 笔记，并将其拆分为
每个主要主题的独立笔记。在它们之间创建维基链接。

安全注意事项

在通过 MCP 将 Obsidian 库连接到 AI 时，请注意以下几点：

• AI 可以读取配置库路径下的所有文件：除非你信任 AI 提供商的数据处理政策，否则请勿连接包含敏感信息（密码、财务数据、私人日记）的库。
• 写权限意味着 AI 可以修改你的笔记：使用 git 或 Obsidian 内置的版本历史记录来保留备份。
• 限制范围：与其连接整个库，不如只连接你希望 AI 访问的特定子文件夹。

{
  "mcpServers": {
    "obsidian-work": {
      "command": "npx",
      "args": [
        "obsidian-mcp-server",
        "--vault",
        "/Users/yourname/Documents/MyVault/Work"
      ]
    }
  }
}

故障排除

“服务器启动失败 (Server failed to start)” 验证是否安装了 Node.js v18+。通过在终端运行命令手动测试服务器。

“找不到笔记 (Note not found)” 错误 检查库路径是否正确且使用了绝对路径。在 Windows 上，使用正斜杠或转义的反斜杠。

大型库运行缓慢 如果你的库有数千条笔记，搜索工具可能会变慢。可以考虑添加内容索引或限制搜索特定文件夹。

Obsidian 文件锁定 Obsidian 不会锁定文件，因此 MCP 服务器可以自由读写。但是，MCP 服务器所做的更改可能不会立即在 Obsidian 中显示——在 Obsidian 中按 Ctrl/Cmd+R 即可刷新文件列表。

总结

通过 MCP 将 Obsidian 连接到 AI，可以将你的静态笔记集合转变为一个 AI 可以查询、分析和扩展的动态知识库。无论你使用预构建的软件包还是 filesystem 服务器，设置只需大约 10 分钟，而自定义服务器方法可以让你完全控制 AI 的访问权限和操作权限。

如果你的项目在进行知识管理的同时还涉及 AI 生成的媒体（如图像、视频或数字人/talking avatars），请查看 Hypereal AI，它提供了一个处理所有这些内容的统一 API。

免费试用 Hypereal AI —— 35 积分，无需信用卡。