内容
# @h4sht/bookstack-mcp
<p align="center">
<img src="https://raw.githubusercontent.com/BookStackApp/BookStack/development/public/icon.png" alt="BookStack" width="120" />
</p>
<p align="center">
<strong>BookStack 的 MCP 服务器</strong> — 将 Claude Code、Codex、OpenCode 和任何 AI 助手连接到您的 BookStack 维基。<br>
<em>一行命令，零配置文件，即刻设置。</em>
</p>
<p align="center">
<a href="https://github.com/h4sht/bookstack-mcp"><img src="https://img.shields.io/badge/github-h4sht%2Fbookstack--mcp-blue?logo=github" alt="GitHub 仓库"></a>
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="MIT 许可证"></a>
<img src="https://img.shields.io/badge/tests-32%2F32-brightgreen" alt="32/32 测试通过">
<img src="https://img.shields.io/badge/node-%3E%3D18-brightgreen?logo=node.js" alt="Node >=18">
</p>
---
## 🚀 Claude Code
```bash
claude mcp add bookstack -- npx github:h4sht/bookstack-mcp
```
Claude Code 将提示您输入：
- `BOOKSTACK_BASE_URL` — 您的 BookStack API URL（例如 `https://wiki.example.com/api`）
- `BOOKSTACK_API_TOKEN` — 您的 API令牌（`token_id:token_secret`）
或者直接传递它们：
```bash
claude mcp add bookstack \
--env BOOKSTACK_BASE_URL=https://wiki.example.com/api \
--env BOOKSTACK_API_TOKEN=token_id:token_secret \
-- npx github:h4sht/bookstack-mcp
```
然后在 Claude Code 中使用 `/mcp` 验证它是否已连接 ✔
---
## 🛠️ 您将获得的工具（25 个）
| 类别 | 工具 |
|----------|-------|
| 📚 **书籍** (6) | list, get, create, update, delete, export |
| 📑 **章节** (6) | list, get, create, update, delete, export |
| 📄 **页面** (6) | list, get, create, update, delete, export |
| 📚 **书架** (5) | list, get, create, update, delete |
| 🔍 **搜索** (1) | 搜索所有内容 |
| ⚙️ **系统** (1) | 实例信息 |
所有 `export_*` 工具都支持 `markdown`、`html`、`pdf`、`plaintext`。
---
## ✍️ Markdown 驱动
BookStack 将页面存储为 HTML，但通过其 API 接受 **Markdown 输入**。这意味着 Claude 可以在本地格式中创建和编辑维基页面：
```
"在书籍 3 中创建一个关于异步 Python 的页面"
→ bookstack_create_page({
book_id: 3,
name: "异步 Python 指南",
markdown: "# 异步 Python\n\n`asyncio` 是 Python 的标准库..."
})
```
页面也会导出为 Markdown，因此 Claude 可以读取、分析和改进现有内容。
---
## 📦 其他 AI 助手的设置
### OpenAI Codex
```bash
codex mcp add bookstack \
--env BOOKSTACK_BASE_URL=https://wiki.example.com/api \
--env BOOKSTACK_API_TOKEN=id:secret \
-- npx github:h4sht/bookstack-mcp
```
或将以下内容添加到 `~/.codex/config.toml`：
```toml
[mcp_servers.bookstack]
command = "npx"
args = ["github:h4sht/bookstack-mcp"]
[mcp_servers.bookstack.env]
BOOKSTACK_BASE_URL = "https://wiki.example.com/api"
BOOKSTACK_API_TOKEN = "id:secret"
```
使用 `codex mcp list` 验证。
### OpenCode
```bash
opencode mcp add
# 选择“local”，然后输入：npx github:h4sht/bookstack-mcp
```
或将以下内容添加到 `opencode.json`：
```jsonc
{
"mcp": {
"bookstack": {
"type": "local",
"command": ["npx", "github:h4sht/bookstack-mcp"],
"enabled": true,
"environment": {
"BOOKSTACK_BASE_URL": "https://wiki.example.com/api",
"BOOKSTACK_API_TOKEN": "id:secret"
}
}
}
}
```
### Cline（VS Code）
将以下内容添加到 Cline MCP 设置文件：
```json
{
"mcpServers": {
"bookstack": {
"command": "npx",
"args": ["github:h4sht/bookstack-mcp"],
"env": {
"BOOKSTACK_BASE_URL": "https://wiki.example.com/api",
"BOOKSTACK_API_TOKEN": "id:secret"
}
}
}
}
```
### 任何支持 MCP 的助手（stdio）
服务器命令始终相同：
```bash
npx github:h4sht/bookstack-mcp
```
将 `BOOKSTACK_BASE_URL` 和 `BOOKSTACK_API_TOKEN` 设置为环境变量。
---
## 🔧 配置参考
| 变量 | 是否必需 | 描述 |
|----------|----------|-------------|
| `BOOKSTACK_BASE_URL` | 是 | 完整的 URL，包括 `/api` |
| `BOOKSTACK_API_TOKEN` | 是 | 格式：`token_id:token_secret` |
| `BOOKSTACK_TIMEOUT` | 否 | 请求超时毫秒（默认值：`30000`） |
---
## 🔒 安全
- **4 个可审计文件** — 在 10 分钟内阅读整个源代码
- **一个依赖项** — 仅 `@modelcontextprotocol/sdk`（官方 Anthropic）
- **原生 fetch()** — 无 HTTP 库，无隐藏请求
- **仅 stdio** — 无开放端口，无网络接口
- **零 telemetry** — 无分析，无跟踪，无调用
- **stderr 日志记录** — 永远不会写入 stdout（MCP 协议完整性）
---
## 🧪 测试
```bash
npm test # 32 个测试，全部通过 ✅
```
---
## 📁 结构
```
@h4sht/bookstack-mcp/
├── src/
│ ├── index.ts # MCP 服务器，stdio 传输，配置
│ ├── client.ts # BookStack REST 客户端（原生 fetch）
│ ├── tools.ts # 25 个 MCP 工具定义 + 处理程序
│ └── types.ts # TypeScript 类型
├── dist/ # 编译后的 JS（可直接运行）
├── tests/ # 32 个单元测试 + 集成测试
├── package.json
└── README.md
```
---
## 📝 许可证
MIT © [h4sht](https://github.com/h4sht)
