# Siyuan Mcp Server

> 为 Claude Desktop 提供思源笔记集成的 Model Context Protocol 服务器

- **Type:** MCP server
- **Install:** `agentstack add mcp-fromsko-siyuan-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Fromsko](https://agentstack.voostack.com/s/fromsko)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** ISC
- **Upstream author:** [Fromsko](https://github.com/Fromsko)
- **Source:** https://github.com/Fromsko/siyuan-mcp-server

## Install

```sh
agentstack add mcp-fromsko-siyuan-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 🧠 思源笔记 MCP 服务器
  
  **为 Claude Desktop 提供思源笔记集成的 Model Context Protocol 服务器**
  
  [](https://www.npmjs.com/package/@fromsko/siyuan-mcp-server)
  [](https://opensource.org/licenses/ISC)
  [](https://www.typescriptlang.org/)
  [](https://nodejs.org/)
  
  🚀 让 AI 助手直接管理您的思源笔记
  

---

## 📖 项目介绍

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

### ✨ 主要特性

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

## 🚀 快速开始

### 📋 环境要求

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

### 📥 安装方式

#### 1. 全局安装（推荐）

```bash
# 使用 npm
npm install -g @fromsko/siyuan-mcp-server

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

#### 2. 直接使用（无需安装）

```bash
npx @fromsko/siyuan-mcp-server
```

#### 3. Docker 方式

```bash
docker pull fromsko/siyuan-mcp-server
```

### ⚙️ 快速配置

#### 环境变量设置

| 环境变量         | 必需 | 说明                                      |
| ---------------- | ---- | ----------------------------------------- |
| `SIYUAN_TOKEN`   | ✅   | 思源笔记 API 令牌，用于身份验证           |
| `SIYUAN_API_URL` | ❌   | 思源笔记 API 地址，默认为 http://localhost:6806，可用于连接远程思源笔记服务 |

#### 本地仓库动态端口配置

SiYuan 桌面端的内核端口可能会在重启后变化。使用本地仓库运行时，可以让 `run-local-mcp.sh` 自动读取 `~/.config/siyuan/port.json` 并设置 `SIYUAN_API_URL`：

如果 MCP 客户端支持直接执行脚本：

```json
{
	"mcpServers": {
		"siyuan": {
			"command": "/path/to/siyuan-mcp-server/run-local-mcp.sh",
			"args": [],
			"env": {
				"SIYUAN_TOKEN": "your-api-token"
			}
		}
	}
}
```

如果 MCP 客户端使用 command 数组格式，可以通过 `/bin/bash` 执行脚本：

```json
{
	"command": [
		"/bin/bash",
		"/path/to/siyuan-mcp-server/run-local-mcp.sh"
	],
	"environment": {
		"SIYUAN_TOKEN": "your-api-token"
	}
}
```

运行前请先启动 SiYuan，并确保本地仓库已经执行过 `npm run build`。

#### 在 Claude Desktop 中配置

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

```json
{
	"mcpServers": {
		"siyuan": {
			"command": "npx",
			"args": ["-y", "@fromsko/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`

#### 命令行直接使用

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

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

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

## 📚 功能与使用

### 🔧 可用工具

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

| 功能类别          | 描述                     | 主要命令     |
| ----------------- | ------------------------ | ------------ |
| 📓 **笔记本管理** | 创建、删除、重命名笔记本 | `notebook.*` |
| 📄 **文档操作**   | 创建、编辑、删除文档     | `filetree.*` |
| 🧱 **块级操作**   | 插入、更新、删除内容块   | `block.*`    |
| 🔍 **搜索功能**   | 全文搜索、SQL 查询       | `search.*`   |
| 📋 **模板系统**   | 模板创建和渲染           | `template.*` |
| 📊 **数据查询**   | 复杂数据库查询           | `sql.*`      |

### 💡 使用示例

#### 1. 创建新笔记本

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

#### 2. 全文搜索内容

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

#### 3. 创建带内容的文档

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

### 🆘 获取帮助

获取特定命令的详细帮助信息：

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

## 🔧 开发指南

### 本地开发环境搭建

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

# 安装依赖
pnpm install

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

# 构建生产版本
pnpm build

# 运行测试
pnpm test
```

### 技术栈与要求

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

### Docker 开发

```bash
# 构建开发镜像
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` 环境变量：
>
> ```bash
> # 连接到远程服务器
> SIYUAN_TOKEN=your-token SIYUAN_API_URL=http://your-server-ip:6806 siyuan-mcp-server
> ```
>
> 或在 Claude Desktop 配置中：
>
> ```json
> {
> 	"mcpServers": {
> 		"siyuan": {
> 			"command": "npx",
> 			"args": ["-y", "@fromsko/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 命令可以正常执行

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

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

### 调试模式

启用详细的调试日志：

```bash
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](https://github.com/fromsko/siyuan-mcp-server/issues)
- 详细描述问题的复现步骤
- 提供相关的错误日志和环境信息

## 📜 开源协议

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

## 🔗 相关资源

### 官方链接

- 📚 [思源笔记官网](https://b3log.org/siyuan/)
- 🔗 [Model Context Protocol](https://modelcontextprotocol.io/)
- 🤖 [Claude Desktop](https://claude.ai/download)
- 📦 [npm 包页面](https://www.npmjs.com/package/@fromsko/siyuan-mcp-server)

### 社区与支持

- 💬 [思源笔记社区](https://ld246.com/domain/siyuan)
- 🐙 [项目 GitHub](https://github.com/fromsko/siyuan-mcp-server)
- 📧 [问题反馈](mailto:hnkong666@gmail.com)

## ❤️ 特别感谢

- 🌟 **原始项目作者** [onigeya](https://github.com/onigeya/siyuan-mcp-server) - 本项目基于其优秀的开源工作进行改进和扩展
- 🙏 [思源笔记](https://github.com/siyuan-note/siyuan) 团队 - 提供优秀的笔记软件
- 🤖 [Anthropic](https://www.anthropic.com/) - 推动 MCP 协议发展
- 👥 所有贡献者和用户 - 让项目变得更好

---

  
  **🌟 如果这个项目对您有帮助，请给我们一个 Star！**
  
  💻 用 TypeScript 和 ❤️ 精心构建

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Fromsko](https://github.com/Fromsko)
- **Source:** [Fromsko/siyuan-mcp-server](https://github.com/Fromsko/siyuan-mcp-server)
- **License:** ISC

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-fromsko-siyuan-mcp-server
- Seller: https://agentstack.voostack.com/s/fromsko
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.