思源笔记 MCP 服务器 是一个专为 思源笔记 设计的 Model Context Protocol 服务器实现。通过此服务器，您可以在 Claude Desktop 或 Claude Code 等支持 MCP 的 AI 客户端中直接操作思源笔记，实现笔记管理、内容搜索、文档编辑等功能的无缝集成。

• 🔗 原生集成 - 在 AI 助手中直接操作思源笔记
• 📚 功能完整 - 支持笔记本、文档、块级操作的全套功能
• 🔍 智能搜索 - 全文检索、SQL 查询、标签搜索等多种搜索方式
• 🛠️ 开发者友好 - TypeScript 编写，提供完整的类型定义和 API 文档
• 📦 简单部署 - 支持 npm、Docker 多种安装方式
• 🔒 安全认证 - 基于 Token 的安全认证机制

• Node.js >= 18.0.0
• 思源笔记 正在运行且已开启 API 服务
• Claude Code / Claude Desktop 或其他支持 MCP 的客户端
• 思源笔记 API Token（设置 → 关于 → API token）

# 使用 npm
npm install -g @uminotou/siyuan-mcp-server

# 使用 pnpm
pnpm add -g @uminotou/siyuan-mcp-server

npx @uminotou/siyuan-mcp-server

docker pull UminoTou/siyuan-mcp-server

第一步： 在你的项目根目录创建 .mcp.json 文件：

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["-y", "@uminotou/siyuan-mcp-server"],
      "env": {
        "SIYUAN_TOKEN": "your-api-token"
      }
    }
  }
}

第二步： 在项目 .claude/settings.local.json 中启用该 MCP 服务器：

{
  "enabledMcpjsonServers": ["siyuan"]
}

第三步： 重启 Claude Code，在对话中输入 /mcp 验证是否出现 siyuan 服务器。

如果需要在所有项目中使用，将 .mcp.json 放到用户目录 ~/.mcp.json，并在 ~/.claude/settings.json 中添加 enabledMcpjsonServers。

在 Claude Desktop 配置文件中添加以下内容：

{
  "mcpServers": {
    "siyuan": {
      "command": "npx",
      "args": ["-y", "@uminotou/siyuan-mcp-server"],
      "env": {
        "SIYUAN_TOKEN": "your-api-token"
      }
    }
  }
}

配置文件位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

# 全局安装后直接使用
SIYUAN_TOKEN=your-token siyuan-mcp-server

# 使用 npx（无需安装）
SIYUAN_TOKEN=your-token npx @uminotou/siyuan-mcp-server

# Docker 运行
docker run --rm -i \
  -e SIYUAN_TOKEN=your-token \
  UminoTou/siyuan-mcp-server

本 MCP 服务器提供以下核心功能：

在思源中创建一个名为"AI 学习笔记"的新笔记本。

{
	"type": "executeCommand",
	"params": {
		"type": "notebook.createNotebook",
		"params": {
			"name": "AI 学习笔记"
		}
	}
}

在所有笔记中按关键词"机器学习"全文检索，返回匹配的文档块及其位置。

{
	"type": "executeCommand",
	"params": {
		"type": "search.fullTextSearch",
		"params": {
			"query": "机器学习",
			"method": 0
		}
	}
}

在指定笔记本中创建 Markdown 文档，一次性写入标题和正文内容。

{
	"type": "executeCommand",
	"params": {
		"type": "filetree.createDocWithMd",
		"params": {
			"notebook": "notebook-id",
			"path": "/今日学习总结",
			"markdown": "# 今日学习总结\n\n## 主要收获\n\n1. 学习了...\n2. 理解了..."
		}
	}
}

获取特定命令的详细帮助信息。返回命令的参数说明、返回值格式和使用示例。

{
	"type": "help",
	"params": {
		"type": "notebook.createNotebook"
	}
}

# 克隆项目
git clone https://github.com/UminoTou/siyuan-mcp-server.git
cd siyuan-mcp-server

# 安装依赖
pnpm install

# 开发模式启动
SIYUAN_TOKEN=your-token pnpm dev

# 构建生产版本
pnpm build

# 运行测试
pnpm test

siyuan-mcp-server/
├── dist/                  # 构建输出
│   └── server.js          # 服务器入口
├── src/                   # 源代码
│   └── server.ts          # 主服务入口
├── package.json
└── README.md

成功启动后应看到类似输出：

🚀 启动思源笔记 MCP 服务器...
✅ 环境变量检查通过
🎉 MCP 服务器启动成功!
📡 等待客户端连接...

• 运行时: Node.js >= 18.0.0
• 语言: TypeScript >= 5.0.0
• 包管理: pnpm（推荐）或 npm
• 框架: @modelcontextprotocol/sdk
• 构建工具: TypeScript Compiler

# 构建开发镜像
docker build -t siyuan-mcp-server:dev .

# 运行开发容器
docker run --rm -it \
  -e SIYUAN_TOKEN=your-token \
  -v $(pwd):/app \
  siyuan-mcp-server:dev

❓ 服务器启动失败，提示"缺少 SIYUAN_TOKEN"

请确保正确设置了 SIYUAN_TOKEN 环境变量。获取方式：思源笔记 → 设置 → 关于 → API token

❓ 无法连接到思源笔记

请检查以下几点：

• 思源笔记是否正在运行
• API 服务是否已开启（默认端口 6806）
• Token 是否正确且未过期
• 防火墙是否阻止了连接
• 如需连接远程思源笔记，请设置 SIYUAN_API_URL 环境变量指向正确的地址（例如：http://your-server-ip:6806）

❓ 如何连接远程思源笔记服务

默认情况下，服务器会连接到 http://localhost:6806。要连接到远程思源笔记服务，请设置 SIYUAN_API_URL 环境变量：

# 连接到远程服务器
SIYUAN_TOKEN=your-token SIYUAN_API_URL=http://your-server-ip:6806 siyuan-mcp-server

或在 Claude Desktop 配置中：

{
	"mcpServers": {
		"siyuan": {
			"command": "npx",
			"args": ["-y", "@uminotou/siyuan-mcp-server"],
			"env": {
				"SIYUAN_TOKEN": "your-api-token",
				"SIYUAN_API_URL": "http://your-server-ip:6806"
			}
		}
	}
}

❓ Claude Desktop 无法识别 MCP 服务器

请尝试以下解决方案：

• 检查配置文件 JSON 格式是否正确
• 重启 Claude Desktop 应用
• 查看 Claude Desktop 日志获取详细错误信息
• 确认 npx 命令可以正常执行

❓ macOS / Linux 提示权限不足

chmod +x dist/server.js

❓ 命令执行失败或返回错误

• 确认思源笔记中存在相应的笔记本或文档
• 检查 Token 权限是否足够
• 查看服务器日志获取详细错误信息

启用详细的调试日志：

DEBUG=siyuan-mcp:* SIYUAN_TOKEN=your-token siyuan-mcp-server

服务器会输出以下类型的日志：

• INFO: 一般信息，如服务启动、连接状态
• WARN: 警告信息，如参数错误、连接异常
• ERROR: 错误信息，如 API 调用失败、认证失败

我们热烈欢迎社区贡献！您可以通过以下方式参与：

1. Fork 项目 - 点击右上角的 Fork 按钮
2. 创建分支 - git checkout -b feature/awesome-feature
3. 提交代码 - git commit -am 'Add awesome feature'
4. 推送分支 - git push origin feature/awesome-feature
5. 创建 PR - 在 GitHub 上创建 Pull Request

• 代码风格: 遵循 TypeScript 严格模式
• 测试覆盖: 为新功能编写单元测试
• 文档更新: 更新相关的 API 文档和使用说明
• 提交规范: 使用清晰的 commit message

发现 Bug 或有改进建议？请通过以下方式报告：

• GitHub Issues
• 详细描述问题的复现步骤
• 提供相关的错误日志和环境信息

本项目采用 ISC 协议开源，详情请查看 LICENSE 文件。

• 📚 思源笔记官网
• 🔗 Model Context Protocol
• 🤖 Claude Desktop
• 📦 npm 包页面

• 💬 思源笔记社区
• 🐙 项目 GitHub
• 📧 问题反馈

• 🌟 原始项目作者 onigeya - 本项目基于其优秀的开源工作进行改进和扩展
• 🙏 思源笔记 团队 - 提供优秀的笔记软件
• 🤖 Anthropic - 推动 MCP 协议发展
• 👥 所有贡献者和用户 - 让项目变得更好