Obsidian MCP 服务器
专为 LLM 与 Obsidian Vault 交互而设计的模型上下文协议服务器。它基于 TypeScript 构建，具有安全的 API 通信、高效的文件操作和全面的搜索功能，使 AI 助手能够通过简洁灵活的工具界面无缝管理知识库。
模型上下文协议（MCP）使AI模型能够通过标准化接口与外部工具和资源进行交互。
需要 Obsidian 中的本地 REST API 插件。
特征
文件操作
- 带验证的原子文件/目录操作
- 资源监控和清理
- 错误处理和优雅失败
搜索系统
- 具有可配置上下文的全文搜索
- 文件、标签和元数据的高级 JsonLogic 查询
- 支持全局模式和前置字段
物业管理
- YAML 前置内容解析和智能合并
- 自动时间戳（由 Obsidian 创建，由服务器修改）
- 自定义字段支持
安全性和性能
- 具有速率限制和 SSL 选项的 API 密钥认证
- 资源监控和健康检查
- 优雅关机处理
安装
注意：需要 Node.js
- 在 Obsidian 中启用本地 REST API 插件
- 克隆并构建：
git clone git@github.com:cyanheads/obsidian-mcp-server.git
cd obsidian-mcp-server
npm install
npm run build
或者从 npm 安装：
npm install obsidian-mcp-server
配置
添加到您的 MCP 客户端设置（例如， claude_desktop_config.json或cline_mcp_settings.json ）：
{
"mcpServers": {
"obsidian-mcp-server": {
"command": "node",
"args": ["/path/to/obsidian-mcp-server/build/index.js"],
"env": {
"OBSIDIAN_API_KEY": "your_api_key_here",
"VERIFY_SSL": "false",
"OBSIDIAN_PROTOCOL": "https",
"OBSIDIAN_HOST": "127.0.0.1",
"OBSIDIAN_PORT": "27124",
"REQUEST_TIMEOUT": "5000",
"MAX_CONTENT_LENGTH": "52428800",
"MAX_BODY_LENGTH": "52428800",
"RATE_LIMIT_WINDOW_MS": "900000",
"RATE_LIMIT_MAX_REQUESTS": "200",
"TOOL_TIMEOUT_MS": "60000"
}
}
}
}
环境变量：
必需的：
OBSIDIAN_API_KEY ：来自 Obsidian 本地 REST API 插件设置的 API 密钥
连接设置：
VERIFY_SSL ：启用 SSL 证书验证（默认值：false）# 对于自签名证书，必须将其设置为 false。如果您在本地运行或不明白其含义，则应将其设置为 false。OBSIDIAN_PROTOCOL ：使用的协议（默认值：“https”）OBSIDIAN_HOST ：主机地址（默认值：“127.0.0.1”）OBSIDIAN_PORT ：端口号（默认值：27124）
请求限制：
REQUEST_TIMEOUT ：请求超时（以毫秒为单位）（默认值：5000）MAX_CONTENT_LENGTH ：最大响应内容长度（以字节为单位）（默认值：52428800 [50MB]）MAX_BODY_LENGTH ：最大请求正文长度（以字节为单位）（默认值：52428800 [50MB]）
速率限制：
RATE_LIMIT_WINDOW_MS ：速率限制窗口（以毫秒为单位）（默认值：900000 [15 分钟]）RATE_LIMIT_MAX_REQUESTS ：每个窗口的最大请求数（默认值：200）
工具执行：
TOOL_TIMEOUT_MS ：工具执行超时（以毫秒为单位）（默认值：60000 [1 分钟]）
项目结构
该项目采用模块化架构，关注点明确分离：
src/
├── index.ts # Main entry point
├── mcp/ # MCP server implementation
├── obsidian/ # Obsidian API client and types
├── resources/ # MCP resource implementations
├── tools/ # MCP tool implementations
│ ├── files/ # File operations tools
│ ├── search/ # Search tools
│ └── properties/ # Property management tools
└── utils/ # Shared utilities
工具
文件管理
// List vault contents
obsidian_list_files_in_vault: {
}
// List directory contents
obsidian_list_files_in_dir: {
dirpath: string; // Path relative to vault root
}
// Get file contents
obsidian_get_file_contents: {
filepath: string; // Path relative to vault root
}
搜索行动
// Text search with context
obsidian_find_in_file: {
query: string,
contextLength?: number // Default: 10
}
// Advanced search with JsonLogic
obsidian_complex_search: {
query: JsonLogicQuery
// Examples:
// Find by tag:
// {"in": ["#mytag", {"var": "frontmatter.tags"}]}
//
// Find markdown files in a directory:
// {"glob": ["docs/*.md", {"var": "path"}]}
//
// Combine conditions:
// {"and": [
// {"glob": ["*.md", {"var": "path"}]},
// {"in": ["#mytag", {"var": "frontmatter.tags"}]}
// ]}
}
// Get all tags in vault or directory
obsidian_get_tags: {
path?: string // Optional: limit to specific directory
}
内容修改
// Append to file
obsidian_append_content: {
filepath: string, // Path relative to vault root
content: string // Content to append
}
// Update file content
obsidian_patch_content: {
filepath: string, // Path relative to vault root
content: string // New content (replaces existing)
}
物业管理
// Get note properties
obsidian_get_properties: {
filepath: string // Path relative to vault root
}
// Update note properties
obsidian_update_properties: {
filepath: string, // Path relative to vault root
properties: {
title?: string,
author?: string,
// Note: created/modified timestamps are managed automatically
type?: Array<"concept" | "architecture" | "specification" |
"protocol" | "api" | "research" | "implementation" |
"guide" | "reference">,
tags?: string[], // Must start with #
status?: Array<"draft" | "in-progress" | "review" | "complete">,
version?: string,
platform?: string,
repository?: string, // URL
dependencies?: string[],
sources?: string[],
urls?: string[], // URLs
papers?: string[],
custom?: Record<string, unknown>
}
}
最佳实践
文件操作
搜索实施
- 使用适合该任务的搜索工具：
- obsidian_find_in_file 用于文本搜索
- obsidian_complex_search 用于元数据/标签过滤
- 保持上下文大小合理（默认值：10 个字符）
物业管理
- 使用适当的类型并验证更新
- 正确处理数组和自定义字段
- 从不设置时间戳（自动管理）
错误预防
资源
MCP 服务器公开以下资源：
obsidian://tags # List of all tags used across the vault
贡献
- 分叉存储库
- 创建功能分支
- 提交拉取请求
对于错误和功能，请在https://github.com/cyanheads/obsidian-mcp-server/issues上创建问题。
出版
当版本标签被推送时，包会自动发布到 npm：
# Update version in package.json
npm version patch # or minor, or major
git push --follow-tags
这将触发 GitHub Action 来构建和发布包。
执照
Apache 许可证 2.0