使用说明

Claude Code的黑曜石MCP服务器

🤖 通过自动格式化和特定于项目的组织，将Claude Code的响应无缝地直接保存到您的黑曜石库中。

概述

此MCP（模型上下文协议）服务器在Claude Code和Obsidian之间建立了一座桥梁，允许您以适当的格式和组织将AI生成的内容（报告、代码审查、文档）直接保存到您的Obsidian保管库中。

✨ 主要特点

🎯 直接积分法：要求Claude Code“保存到黑曜石”，它会自动发生
📁 项目具体组织：为每个项目配置自定义文件夹和模板
🎨 丰富的格式：自动前台、时间戳和结构化模板
⚙️ 轻松设置：具有交互式配置的一个命令安装
🔧 灵活的模板：可定制的报告、评论和笔记模板
🔗 黑曜石URL支持：通过空格/特殊字符处理直接从黑曜石URL读取文件

快速开始

1.安装

克隆此存储库并运行交互式安装程序：

git clone https://github.com/robwilde/obsidian-mcp-server.git
cd obsidian-mcp-server
python3 install.py

安装程序将：

✅ 检查Python 3.8+并安装MCP依赖项
✅ 提示您的黑曜石保险库路径
✅ 全局安装MCP服务器 ~/.claude/
✅ 自动配置Claude代码设置
✅ 可选择创建特定于项目的配置

2.使用方法

安装后，只需询问Claude Code：

"Create a security review of the authentication system and save to Obsidian"
"Generate API documentation and save it to Obsidian as a report"
"Document the database schema and save to Obsidian"
"Read this Obsidian file: obsidian://open?vault=MyVault&file=Notes/ProjectPlan"
"@obsidian obsidian://open?vault=MyVault&file=Docs%2FMeeting%20Notes%202025"

Claude Code将自动使用适当的工具与您的黑曜石保险库进行交互。

项目配置

全局设置

MCP服务器是全局安装的，并通过以下方式进行配置 ~/.claude/settings.json:

{
  "mcpServers": {
    "obsidian-claude-code": {
      "command": "python3",
      "args": ["/home/user/.claude/obsidian_mcp_server.py"],
      "env": {
        "OBSIDIAN_VAULT_PATH": "/path/to/your/obsidian/vault"
      }
    }
  }
}

项目特定配置

每个项目都可以在中具有自定义设置 .claude/obsidian.json:

{
  "folder": "Projects/My Awesome Project",
  "templates": {
    "report": "# {title}\n\n**📋 Report Generated**\n- **Date:** {timestamp}\n- **Project:** {project}\n\n{content}",
    "review": "# Code Review: {title}\n\n**👀 Review Details**\n- **Date:** {timestamp}\n- **Project:** {project}\n\n{content}",
    "note": "# {title}\n\n**📝 Note**\n- **Created:** {timestamp}\n- **Project:** {project}\n\n{content}"
  }
}

将项目配置添加到现有项目

python3 install.py --project-config

文件结构

obsidian-mcp-server/
├── README.md                              # This file
├── install.py                             # Interactive installer
├── obsidian_mcp_server.py                 # Main MCP server
├── hook.py                                # Claude Code hook script (optional)
├── CLAUDE.md                              # Development guidance
├── .claude/obsidian.json                  # Example project config
└── Building an MCP Server...md            # Detailed implementation guide

运作原理

建筑

MCP服务器：作为后台服务运行，为Claude Code提供工具
项目检测：自动检测项目上下文和配置
模板引擎：使用可自定义模板格式化内容
文件组织：将文件保存到vault中特定于项目的文件夹中

可用工具

MCP服务器为Claude Code提供以下工具：

save_to_obsidian：使用模板保存格式化内容的主要工具
read_obsidian_url：从黑曜石URL读取文件（处理空格和特殊字符的URL编码）
save_claude_response：直接响应保存（如果通过钩子实现）
list_vault_files：浏览现有vault文件（计划）
get_vault_structure：查看vault文件夹层次结构（计划）

生成的文件格式

文件会自动保存为：

---
created: 2025-01-27T14:30:22.123456
source: claude-code
tags: [claude-code, report, project-name]
---

# Security Review: Authentication System

**📋 Report Generated**
- **Date:** 2025-01-27 14:30:22
- **Project:** my-awesome-project
- **Type:** Technical Report

---

[Your content here, formatted according to the template]

---

*Generated by Claude Code*

需求

Python 3.8+
克劳德代码 （有MCP支持）
黑曜石 （任何最新版本）
MCP Python包 （由安装程序自动安装）

高级用法

阅读黑曜石网址

这 read_obsidian_url 该工具允许Claude Code直接从黑曜石网址读取文件：

# Basic usage
"Read file from: obsidian://open?vault=MyVault&file=Notes/ProjectPlan"

# With URL-encoded spaces and special characters
"@obsidian obsidian://open?vault=MyVault&file=Meeting%20Notes%2FQ1%202025"

# Files with special characters in names
"Read: obsidian://open?vault=DevNotes&file=Issues%2FWAI-130%20Assignee%20field"

该工具自动执行以下操作：

从URL解析vault名称和文件路径
处理URL编码字符（空格、斜线、特殊字符）
添加.md扩展名（如果不存在）
使用已配置的 OBSIDIAN_VAULT_PATH 查找文件

自定义模板

修改 .claude/obsidian.json 自定义不同内容类型的格式：

{
  "templates": {
    "security-review": "# 🔒 Security Review: {title}\n\n**Reviewed by:** Claude Code\n**Date:** {timestamp}\n\n## Executive Summary\n\n{content}",
    "api-docs": "# 📚 API Documentation: {title}\n\n**Generated:** {timestamp}\n**Version:** 1.0\n\n{content}"
  }
}

环境变量

OBSIDIAN_VAULT_PATH：黑曜石保险库的路径（由安装程序设置）

调试

通过设置启用调试日志记录：

export MCP_DEBUG=1

故障排除

常见问题

未找到MCP服务器

# Reinstall MCP dependencies
pip install --upgrade mcp

未找到保险库路径

# Check environment variable
echo $OBSIDIAN_VAULT_PATH

# Or update settings manually
vim ~/.claude/settings.json

未检测到项目配置

# Create project config in current directory
python3 install.py --project-config

支持

检查 CLAUDE.md 开发指导文件
查阅文档中的详细实施指南
确保安装后重新启动Claude Code

贡献

分叉存储库
创建要素分支
进行更改
使用安装脚本进行测试
提交拉取请求

许可证

MIT许可证-有关详细信息，请参阅许可证文件。

致谢

为克劳德代码生态系统
使用模型上下文协议（MCP）
与集成黑曜石知识管理

由以下材料制成❤️ Claude Code社区