# Obsidian MCP Server

[English](#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

```bash
# 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)**

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

**Option B: Permanent (add to shell profile)**

```bash
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`:

```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

| Tool          | Description                     |
| ------------- | ------------------------------- |
| `create_note` | Create a new note               |
| `read_note`   | Read note content and metadata  |
| `update_note` | Update note content or metadata |
| `delete_note` | Delete a note                   |
| `list_notes`  | List notes with pagination      |

#### Search Tools

| Tool                  | Description                   |
| --------------------- | ----------------------------- |
| `search_notes`        | Full-text search across notes |
| `search_notes_by_tag` | Search notes by tag           |

#### Folder Tools

| Tool            | Description                 |
| --------------- | --------------------------- |
| `list_folders`  | List vault folder structure |
| `create_folder` | Create a new folder         |
| `delete_folder` | Delete a folder             |

#### Tag Tools

| Tool                  | Description                   |
| --------------------- | ----------------------------- |
| `list_tags`           | List all tags in the vault    |
| `get_note_tags`       | Get tags for a specific note  |
| `search_notes_by_tag` | Find notes with specific tags |

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

```bash
# 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:

   ```bash
   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**:

   ```bash
   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**:

   ```bash
   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/`):
   ```bash
   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:
   ```bash
   echo $OBSIDIAN_VAULT_PATH
   ```
3. Try running the server manually to see error messages:
   ```bash
   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
```

---

## 中文

### 概述

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

### 功能特性

- **完整的笔记管理**：创建、读取、更新和删除笔记
- **强大的搜索功能**：使用 Fuse.js 进行全文搜索和模糊匹配
- **文件夹操作**：导航和管理保险库的文件夹结构
- **标签管理**：提取、列出和按标签搜索笔记
- **实时索引**：自动为您的保险库建立索引以实现快速搜索
- **本地优先**：数据不会离开您的机器

### 环境要求

- Node.js 18+
- pnpm（推荐）或 npm
- Obsidian 保险库

### 安装

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

# 安装依赖
pnpm install

# 构建项目
pnpm build
```

### 配置

#### 1. 设置环境变量

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

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

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

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

```bash
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`：

```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/您的保险库`

### 可用工具

#### 笔记工具

| 工具          | 描述                 |
| ------------- | -------------------- |
| `create_note` | 创建新笔记           |
| `read_note`   | 读取笔记内容和元数据 |
| `update_note` | 更新笔记内容或元数据 |
| `delete_note` | 删除笔记             |
| `list_notes`  | 列出笔记（支持分页） |

#### 搜索工具

| 工具                  | 描述           |
| --------------------- | -------------- |
| `search_notes`        | 全文本搜索笔记 |
| `search_notes_by_tag` | 按标签搜索笔记 |

#### 文件夹工具

| 工具            | 描述                 |
| --------------- | -------------------- |
| `list_folders`  | 列出保险库文件夹结构 |
| `create_folder` | 创建新文件夹         |
| `delete_folder` | 删除文件夹           |

#### 标签工具

| 工具                  | 描述                   |
| --------------------- | ---------------------- |
| `list_tags`           | 列出保险库中的所有标签 |
| `get_note_tags`       | 获取特定笔记的标签     |
| `search_notes_by_tag` | 查找包含特定标签的笔记 |

### 使用示例

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

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

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

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

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

### 开发

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

# 类型检查
pnpm typecheck

# 代码检查
pnpm lint
```

### 常见问题排查

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

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

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

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

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

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

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

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

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

2. **验证配置文件路径**：

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

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

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

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

5. **检查输出目录**：服务器使用 `dist/` 目录（而非 `build/`）：
   ```bash
   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. 验证环境变量设置正确：
   ```bash
   echo $OBSIDIAN_VAULT_PATH
   ```
3. 尝试手动运行服务器查看错误信息：
   ```bash
   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