使用说明

黑曜石MCP服务器

MCP（模型上下文协议）服务器，用于将AI助手与黑曜石保险库集成。支持stdio和HTTP/SSE传输，以实现最大兼容性。

特性

会话报告：自动保存编码会话摘要和元数据
笔记管理：创建、阅读、附加和搜索笔记
每日笔记集成：自动附加到每日笔记
TODO跟踪：创建和管理具有优先级和截止日期的TODO
反向链接发现：查找链接到特定注释的注释
智能链接：根据关键字获取相关笔记的建议
双重运输：支持stdio（直接）和HTTP/SSE（网络）模式

Docker快速入门（推荐）

运行服务器最简单的方法是使用Docker Compose：

# Clone the repository
git clone https://github.com/igorilic/obsidian-mcp.git
cd obsidian-mcp

# Create your environment file
cp .env.example .env

# Edit .env and set your vault path
# OBSIDIAN_VAULT_HOST_PATH=/path/to/your/obsidian/vault

# Start the server
docker compose up -d

# Verify it's running
curl http://localhost:9111/health

服务器将在以下时间可用 http://localhost:9111/mcp.

安装（本地）

先决条件

Node.js 18+
npm或pnpm

步骤

git clone https://github.com/igorilic/obsidian-mcp.git
cd obsidian-mcp
npm install
npm run build

客户端设置

克劳德代码（CLI）

Claude Code原生支持HTTP传输。添加到您的全局配置 ~/.claude.json:

{
  "mcpServers": {
    "obsidian": {
      "type": "http",
      "url": "http://localhost:9111/mcp"
    }
  }
}

或者对于stdio传输（直接，无Docker）：

{
  "mcpServers": {
    "obsidian": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

添加后，重新启动Claude Code或运行 /mcp 重新连接。

克劳德桌面版

Claude Desktop仅支持stdio传输，因此请使用 mcp-remote 作为HTTP服务器的桥梁。

配置位置：

macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
窗户： %APPDATA%\Claude\claude_desktop_config.json

对于HTTP传输（使用Docker）：

{
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "http://localhost:9111/mcp"]
    }
  }
}

对于stdio传输（直接，无Docker）：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

更改后重新启动Claude Desktop。

光标

Cursor支持具有stdio、SSE和HTTP传输的MCP服务器。

配置位置：

全球的： ~/.cursor/mcp.json
项目： .cursor/mcp.json

对于stdio传输：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

对于HTTP传输：

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:9111/mcp",
      "transport": "sse"
    }
  }
}

或者通过用户界面进行配置： File → 偏好设置→ 光标设置→ MCP

文档：光标MCP文档

帆板运动

Windsurf使用与Claude Desktop相同的配置格式。

配置位置： ~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

或者通过用户界面进行配置： 风帆设置→ 级联→ 插件

文档： Windsurf MCP文档

泽德

Zed具有内置的MCP支持，但目前仅支持stdio传输（不支持HTTP）。

配置位置： ~/.config/zed/settings.json

{
  "context_servers": {
    "obsidian": {
      "command": {
        "path": "node",
        "args": ["/path/to/obsidian-mcp/dist/index.js"],
        "env": {
          "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
        }
      }
    }
  }
}

验证：检查代理面板设置-绿色指示器表示服务器处于活动状态。

文档： Zed MCP文件

VS代码并继续

继续通过YAML配置文件支持MCP服务器。

配置位置： 创建 .continue/mcpServers/obsidian.yaml 在您的工作区或主目录中：

对于stdio传输：

name: Obsidian MCP Server
version: 1.0.0
schema: v1
mcpServers:
  - name: obsidian
    command: node
    args:
      - /path/to/obsidian-mcp/dist/index.js
    env:
      OBSIDIAN_VAULT_PATH: /path/to/your/obsidian/vault

对于HTTP传输：

name: Obsidian MCP Server
version: 1.0.0
schema: v1
mcpServers:
  - name: obsidian
    type: streamable-http
    url: http://localhost:9111/mcp

文档：继续MCP文档

VS代码与Cline

克莱恩支持stdio和SSE传输。

点击 MCP服务器 Cline顶部导航中的图标→ 配置 → 高级MCP设置

对于stdio传输：

{
  "mcpServers": {
    "obsidian": {
      "command": "node",
      "args": ["/path/to/obsidian-mcp/dist/index.js"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

对于SSE/HTTP传输：

{
  "mcpServers": {
    "obsidian": {
      "url": "http://localhost:9111/mcp",
      "transport": "sse"
    }
  }
}

文档：临床MCP文档

JetBrains集成开发环境（IntelliJ、WebStorm、PyCharm等）

JetBrains AI Assistant从版本2025.1开始支持MCP服务器。

通过UI设置：

首选 设置→ 工具→ AI助手→ 模型上下文协议（MCP）
点击 + 添加新服务器
配置服务器

对于stdio传输：

{
  "command": "node",
  "args": ["/path/to/obsidian-mcp/dist/index.js"],
  "env": {
    "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
  }
}

注： MCP工具仅在聊天窗口中启用“代码库”模式时工作。

文档： JetBrains MCP文档

通用HTTP客户端

对于支持HTTP/SSE MCP传输的任何客户端：

端点: http://localhost:9111/mcp
健康检查: http://localhost:9111/health
协议：基于流式HTTP的MCP（SSE响应）
必需的标题: Accept: application/json, text/event-stream

初始化请求示例：

curl -X POST http://localhost:9111/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2024-11-05",
      "capabilities": {},
      "clientInfo": {"name": "my-client", "version": "1.0.0"}
    }
  }'

运输方式

HTTP/SSE传输（Docker的默认设置）

最适合：

多个客户端同时连接
网络/远程访问
集装箱化部署

# Using Docker
docker compose up -d

# Or manually
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 node dist/index.js

标准传输（默认为本地）

最适合：

与IDE直接集成
单客户端使用
减少延迟

OBSIDIAN_VAULT_PATH=/path/to/vault node dist/index.js

可用工具

工具	说明
`write_session_report`	使用元数据保存编码会话摘要
`write_note`	创建或覆盖笔记
`append_to_note`	将内容附加到现有注释中
`append_to_daily_note`	添加到今天的每日笔记中
`search_notes`	按内容、标签或文件夹搜索笔记
`read_note`	阅读笔记的内容和封面
`list_recent_notes`	列出最近修改的注释
`find_backlinks`	查找链接到特定笔记的笔记
`create_todo`	创建TODO项目
`link_notes`	获取相关笔记的建议

工具详细信息

write_session_report

{
  title: string;           // Short title (required)
  summary: string;         // Brief summary (required)
  details?: string;        // Detailed description
  files_changed?: string[]; // List of modified files
  next_steps?: string[];   // Follow-up TODOs
  tags?: string[];         // Tags for categorization
  project?: string;        // Project name
  folder?: string;         // Subfolder in Claude-Sessions
}

write_note

{
  path: string;            // Relative path (required)
  content: string;         // Markdown content (required)
  title?: string;          // Note title
  tags?: string[];         // Tags
  frontmatter?: object;    // Additional frontmatter
}

search_notes

{
  query: string;           // Search query (required)
  tags?: string[];         // Filter by tags
  folder?: string;         // Limit to folder
  limit?: number;          // Max results (default: 20)
}

create_todo

{
  task: string;            // Task description (required)
  project?: string;        // Project tag
  priority?: string;       // "high" | "medium" | "low"
  due_date?: string;       // YYYY-MM-DD format
  context?: string;        // Additional context
  todo_file?: string;      // Target file (default: "TODOs.md")
}

环境变量

变量	描述	默认值
`OBSIDIAN_VAULT_PATH`	黑曜石保险库路径	必填
`MCP_TRANSPORT`	运输方式： `stdio` 或 `http`	`stdio`
`MCP_HTTP_PORT`	HTTP服务器端口（使用HTTP传输时）	`3000`

拱顶结构

服务器创建/使用此结构：

Your Vault/
├── Claude-Sessions/           # Session reports
│   ├── project-name/         # Per-project folders
│   │   └── 2024-01-15-1430-feature-complete.md
│   └── 2024-01-15-1200-quick-fix.md
├── Daily Notes/              # Daily notes (configurable)
│   └── 2024-01-15.md
└── TODOs.md                  # TODO items

发展

# Watch mode
npm run dev

# Build
npm run build

# Run with stdio
OBSIDIAN_VAULT_PATH=/path/to/vault npm start

# Run with HTTP
MCP_TRANSPORT=http npm start

# Docker build
docker compose build

# Docker logs
docker compose logs -f

故障排除

“服务器未初始化”错误

MCP客户端的会话已过时。解决：

克劳德代码：运行 /mcp 重新连接
克劳德桌面版：重新启动应用程序
码头工人：运行 docker compose restart

连接被拒绝

确保服务器正在运行：

curl http://localhost:9111/health

写笔记的权限被拒绝

如果使用Docker，请确保vault以写访问权限挂载(:rw 不 :ro)在你的 .env 文件。

MCP工具未出现

检查服务器日志： docker compose logs
验证配置路径是否正确
重新启动IDE/客户端
对于JetBrains：确保启用了“代码库”模式

Zed显示“服务器未激活”

Zed还不支持HTTP传输。请改用stdio配置。

许可证

麻省理工学院

使用说明

黑曜石MCP服务器

特性

Docker快速入门（推荐）

安装（本地）

先决条件

步骤

客户端设置

克劳德代码（CLI）

克劳德桌面版

光标

帆板运动

泽德

VS代码并继续

VS代码与Cline

JetBrains集成开发环境（IntelliJ、WebStorm、PyCharm等）

通用HTTP客户端

运输方式

HTTP/SSE传输（Docker的默认设置）

标准传输（默认为本地）

可用工具

工具详细信息

环境变量

拱顶结构

发展

故障排除

“服务器未初始化”错误

连接被拒绝

写笔记的权限被拒绝

MCP工具未出现

Zed显示“服务器未激活”

许可证

相关 MCP

小红书MCP服务

Figma MCP集成工具

MCP 协议测试服务器

Qdrant向量搜索MCP服务器

Flomo笔记服务

Unity编辑器AI集成插件