Obsidian MCP Server

English | 中文

English

Overview

Obsidian MCP Server is a Model Context Protocol (MCP) server that enables AI assistants to access and manage your local Obsidian vault through a standardized protocol. All data processing happens locally on your machine, ensuring privacy and offline functionality.

Features

• Full Note Management: Create, read, update, and delete notes

• Powerful Search: Full-text search with fuzzy matching using Fuse.js

• Folder Operations: Navigate and manage your vault's folder structure

• Tag Management: Extract, list, and search notes by tags

• Real-time Indexing: Automatically indexes your vault for fast searches

• Local-first: No data leaves your machine

Prerequisites

• Node.js 18+

• pnpm (recommended) or npm

• An Obsidian vault

Installation

# Clone or navigate to the project
cd obsidian-mcp-server

# Install dependencies
pnpm install

# Build the project
pnpm build

Configuration

1. Set Environment Variable

The server requires your Obsidian vault path. You can set it in multiple ways:

Option A: Temporary (current terminal only)

export OBSIDIAN_VAULT_PATH="/Users/yourname/Documents/Obsidian Vault"

Option B: Permanent (add to shell profile)

echo 'export OBSIDIAN_VAULT_PATH="/Users/yourname/Documents/Obsidian Vault"' >> ~/.zshrc
source ~/.zshrc

2. Configure MCP Client

Claude Desktop (macOS)

Create or edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/absolute/path/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/yourname/Documents/Obsidian Vault"
      }
    }
  }
}

Important: Use absolute paths, not ~ or relative paths.

Cursor IDE

1. Open Cursor Settings

2. Search for "MCP" in settings

3. Add a new MCP server with:

   • Name: obsidian

   • Command: node

   • Args: /absolute/path/to/obsidian-mcp-server/dist/index.js

   • Env: OBSIDIAN_VAULT_PATH=/Users/yourname/Documents/Obsidian Vault

Cline MCP

1. Open Cline Settings

2. Navigate to MCP section

3. Add a new MCP server:

   • Name: obsidian

   • Command: node

   • Args: /absolute/path/to/obsidian-mcp-server/dist/index.js

   • Env: OBSIDIAN_VAULT_PATH=/Users/yourname/Documents/Obsidian Vault

Other MCP Clients

Configure with these parameters:

• Command: node

• Args: /absolute/path/to/obsidian-mcp-server/dist/index.js

• Env: OBSIDIAN_VAULT_PATH=/absolute/path/to/your/vault

Available Tools

Note Tools

Search Tools

Folder Tools

Tag Tools

Usage Examples

# Search for notes containing "machine learning"
搜索包含"机器学习"的笔记

# List all notes with #work tag
列出所有包含#工作标签的笔记

# Read a specific note
读取我的项目笔记

# Create a new note
创建一篇新的读书笔记

# List folder structure
列出保险库的文件夹结构

Development

# Run in development mode (auto-reload)
pnpm dev

# Type check
pnpm typecheck

# Lint
pnpm lint

Troubleshooting

"fs.readFile is not a function" or similar filesystem errors

This error typically occurs when the fs-extra module fails to load properly. The solution is to:

1. Clean and reinstall dependencies:

   rm -rf node_modules pnpm-lock.yaml
   pnpm install
   pnpm build

2. Ensure you're using the compiled JavaScript in the dist/ directory, not the TypeScript source files.

Tools not appearing in Claude/Cursor/Cline

1. Check if server starts correctly:

   cd /path/to/obsidian-mcp-server
   OBSIDIAN_VAULT_PATH=/your/vault/path pnpm start

   The server should run without errors and keep running.

2. Verify configuration file path:

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

   Ensure the path is absolute and correct.

3. Check path permissions: Ensure the user running the MCP client has read/write access to your vault.

4. Restart MCP client completely after configuration changes.

5. Check output directory: The server uses dist/ directory (not build/):

   ls /path/to/obsidian-mcp-server/dist/

"Unknown tool" errors

1. Make sure the tool name is exactly as documented. Tool names are case-sensitive.

2. Check that the server started successfully without errors.

3. Verify the correct dist/index.js file is being used.

Empty search results

1. Verify OBSIDIAN_VAULT_PATH points to the correct folder

2. Check that your vault contains .md files

3. Ensure the path is absolute, not relative or using ~

4. Check that notes are in the expected location (not in .obsidian or node_modules)

Server starts but tools don't work

1. Check if there are errors in the server output

2. Verify environment variable is set correctly:

   echo $OBSIDIAN_VAULT_PATH

3. Try running the server manually to see error messages:

   OBSIDIAN_VAULT_PATH="/Users/yourname/Documents/Obsidian Vault" node dist/index.js

Project Structure

obsidian-mcp-server/
├── src/
│   ├── index.ts              # Main entry point
│   ├── types/
│   │   └── obsidian.ts       # TypeScript type definitions
│   ├── services/
│   │   ├── vault-manager.ts  # Vault management (file system operations)
│   │   ├── note-parser.ts    # Note parsing (frontmatter, links)
│   │   ├── search-engine.ts  # Search engine (Fuse.js integration)
│   │   └── tag-manager.ts    # Tag management
│   └── tools/
│       ├── note-tools.ts     # Note operation tools
│       ├── search-tools.ts   # Search tools
│       ├── folder-tools.ts   # Folder management tools
│       └── tag-tools.ts      # Tag operation tools
├── dist/                     # Compiled JavaScript (TypeScript output)
├── package.json
└── tsconfig.json

Related MCP server: Obsidian MCP Tool Server

中文

概述

Obsidian MCP Server 是一个 Model Context Protocol (MCP) 服务器，使 AI 助手能够通过标准化协议访问和管理您的本地 Obsidian 保险库。所有数据处理都在本地机器上完成，确保隐私和离线功能。

功能特性

• 完整的笔记管理：创建、读取、更新和删除笔记

• 强大的搜索功能：使用 Fuse.js 进行全文搜索和模糊匹配

• 文件夹操作：导航和管理保险库的文件夹结构

• 标签管理：提取、列出和按标签搜索笔记

• 实时索引：自动为您的保险库建立索引以实现快速搜索

• 本地优先：数据不会离开您的机器

环境要求

• Node.js 18+

• pnpm（推荐）或 npm

• Obsidian 保险库

安装

# 克隆或进入项目目录
cd obsidian-mcp-server

# 安装依赖
pnpm install

# 构建项目
pnpm build

配置

1. 设置环境变量

服务器需要您的 Obsidian 保险库路径。您可以通过多种方式设置：

方式 A：临时设置（仅当前终端有效）

export OBSIDIAN_VAULT_PATH="/Users/您的用户名/Documents/Obsidian Vault"

方式 B：永久设置（添加到 shell 配置文件）

echo 'export OBSIDIAN_VAULT_PATH="/Users/您的用户名/Documents/Obsidian Vault"' >> ~/.zshrc
source ~/.zshrc

2. 配置 MCP 客户端

Claude Desktop (macOS)

创建或编辑 ~/Library/Application Support/Claude/claude_desktop_config.json：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/绝对路径/to/obsidian-mcp-server/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/Users/您的用户名/Documents/Obsidian Vault"
      }
    }
  }
}

重要提示：请使用绝对路径，不要使用 ~ 或相对路径。

Cursor IDE

1. 打开 Cursor 设置

2. 在设置中搜索 "MCP"

3. 添加新的 MCP 服务器：

   • 名称：obsidian

   • 命令：node

   • 参数：/绝对路径/to/obsidian-mcp-server/dist/index.js

   • 环境变量：OBSIDIAN_VAULT_PATH=/Users/您的用户名/Documents/Obsidian Vault

Cline MCP

1. 打开 Cline 设置

2. 进入 MCP 部分

3. 添加新的 MCP 服务器：

   • 名称：obsidian

   • 命令：node

   • 参数：/绝对路径/to/obsidian-mcp-server/dist/index.js

   • 环境变量：OBSIDIAN_VAULT_PATH=/Users/您的用户名/Documents/Obsidian Vault

其他 MCP 客户端

使用以下参数配置：

• 命令：node

• 参数：/绝对路径/to/obsidian-mcp-server/dist/index.js

• 环境变量：OBSIDIAN_VAULT_PATH=/绝对路径/to/您的保险库

可用工具

笔记工具

搜索工具

文件夹工具

标签工具

使用示例

# 搜索包含"机器学习"的笔记
搜索包含"机器学习"的笔记

# 列出所有包含#工作标签的笔记
列出所有包含#工作标签的笔记

# 读取特定笔记
读取我的项目笔记

# 创建新笔记
创建一篇新的读书笔记

# 列出文件夹结构
列出保险库的文件夹结构

开发

# 开发模式运行（自动重载）
pnpm dev

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint

常见问题排查

"fs.readFile is not a function" 或类似的文件系统错误

此错误通常发生在 fs-extra 模块无法正确加载时。解决方案：

1. 清理并重新安装依赖：

   rm -rf node_modules pnpm-lock.yaml
   pnpm install
   pnpm build

2. 确保使用 dist/ 目录中的编译后 JavaScript 文件，而非 TypeScript 源文件。

工具没有出现在 Claude/Cursor/Cline 中

1. 检查服务器是否正确启动：

   cd /path/to/obsidian-mcp-server
   OBSIDIAN_VAULT_PATH=/您的/保险库/路径 pnpm start

   服务器应该正常运行且保持运行状态。

2. 验证配置文件路径：

   cat ~/Library/Application\ Support/Claude/claude_desktop_config.json

   确保路径是绝对且正确的。

3. 检查路径权限：确保运行 MCP 客户端的用户对您的保险库有读写权限。

4. 完全重启 MCP 客户端：配置更改后需要完全重启。

5. 检查输出目录：服务器使用 dist/ 目录（而非 build/）：

   ls /path/to/obsidian-mcp-server/dist/

"Unknown tool" 错误

1. 确保工具名称与文档中完全一致。工具名称区分大小写。

2. 检查服务器是否成功启动且没有错误。

3. 验证使用的是正确的 dist/index.js 文件。

搜索结果为空

1. 验证 OBSIDIAN_VAULT_PATH 指向正确的文件夹

2. 检查您的保险库是否包含 .md 文件

3. 确保路径是绝对的，不是相对路径或使用 ~

4. 检查笔记是否在预期位置（不在 .obsidian 或 node_modules 中）

服务器启动但工具无法工作

1. 检查服务器输出中是否有错误

2. 验证环境变量设置正确：

   echo $OBSIDIAN_VAULT_PATH

3. 尝试手动运行服务器查看错误信息：

   OBSIDIAN_VAULT_PATH="/Users/您的用户名/Documents/Obsidian Vault" node dist/index.js

项目结构

obsidian-mcp-server/
├── src/
│   ├── index.ts              # 主入口
│   ├── types/
│   │   └── obsidian.ts       # TypeScript 类型定义
│   ├── services/
│   │   ├── vault-manager.ts  # 保险库管理（文件系统操作）
│   │   ├── note-parser.ts    # 笔记解析（frontmatter、链接）
│   │   ├── search-engine.ts  # 搜索引擎（Fuse.js 集成）
│   │   └── tag-manager.ts    # 标签管理
│   └── tools/
│       ├── note-tools.ts     # 笔记操作工具
│       ├── search-tools.ts   # 搜索工具
│       ├── folder-tools.ts   # 文件夹管理工具
│       └── tag-tools.ts      # 标签操作工具
├── dist/                     # 编译后的 JavaScript（TypeScript 输出）
├── package.json
└── tsconfig.json

许可证

MIT License