BookStack MCP Server

BookStack MCP游标服务器

一个最小的Python MCP（模型上下文协议）服务器，允许Cursor AI管理您的BookStack文档。

特性

此服务器提供基本的BookStack管理工具：

• 列表内容：浏览书籍、书架、章节和页面
• 搜索：对所有内容进行全文搜索
• 页面管理：创建、读取、更新和删除页面
• 图书管理：创建新书
• 章节管理：创建新章节

先决条件

• Python 3.8或更高版本
• 具有API访问权限的BookStack实例
• BookStack API令牌（ID和Secret）

设置

1.安装依赖项

pip install -r requirements.txt

2.配置环境

首先，您需要在BookStack中创建一个API令牌：

1. 登录到您的BookStack实例http://192.168.1.193:6875
2. 转到您的个人资料→ API令牌
3. 创建具有适当权限的新令牌
4. 复制令牌ID和令牌密钥

然后创建一个 .env 文件：

cp .env.example .env

编辑 .env 并添加您的BookStack凭据：

BS_URL=http://192.168.1.193:6875
BS_TOKEN_ID=your_actual_token_id
BS_TOKEN_SECRET=your_actual_token_secret

3.测试服务器

直接运行服务器进行测试：

python server.py

服务器将启动并通过stdio监听MCP协议消息。

光标集成

要将此MCP服务器与Cursor一起使用，请将其添加到Cursor MCP设置中：

1. 打开光标设置（Cmd/Ctrl+，）
2. 导航至 特性 → 模型上下文协议
3. 添加新的服务器配置：

{
  "mcpServers": {
    "bookstack": {
      "command": "python",
      "args": ["/home/borjigin/dev/bookstack-mcp/server.py"],
      "env": {
        "BS_URL": "http://192.168.1.193:6875",
        "BS_TOKEN_ID": "your_token_id",
        "BS_TOKEN_SECRET": "your_token_secret"
      }
    }
  }
}

或者使用脚本包装器：

{
  "mcpServers": {
    "bookstack": {
      "command": "/home/borjigin/dev/bookstack-mcp/run_server.sh"
    }
  }
}

1. 重新启动游标

可用工具

配置后，您可以要求Cursor与BookStack交互：

列表内容

• “列出BookStack中的所有书籍”
• “给我看第五册的章节”
• “查找名称中包含“API”的页面”

搜索

• “在BookStack中搜索“身份验证””
• “查找有关Docker的文档”

阅读内容

• “获取第42页的内容”
• “显示页面ID 10中的内容”

创建内容

• “创建一本名为“API文档”的新书”
• “在第5册中创建一个名为“入门”的章节”
• “在第3册中创建一个包含降价内容的页面…”

更新内容

• “更新第15页，将标题更改为“新标题””
• “使用此标记修改第20页的内容…”

删除内容

• “删除第99页”

工具参考

书架_列表_内容

列出内容实体（书籍、书架、章节、页面）

• entity_type：“书籍”|“书架”|“章节”|“页面”
• count：项目数（默认值为20）
• offset：分页偏移量（默认值0）
• filter_name：按名称子字符串筛选

书架_搜索

搜索所有内容

• query：搜索查询字符串
• page：页码（默认1）
• count：每页结果数（默认值为20）

书架_get_page

获取页面详细信息和内容

• page_id：页面ID

书架_创意_页面

创建新页面

• book_id：图书ID（必填）
• name：页面标题（必填）
• html 或 markdown：内容（需要一个）
• chapter_id：可选章节ID
• tags：可选标记（格式：“tag1=value1，tag2=value2”）

书架更新页面

更新现有页面

• page_id：页面ID（必填）
• name：新标题（可选）
• html 或 markdown：新内容（可选）
• tags：可选标签

bookback_delete_page

删除页面

• page_id：页面ID（必填）

书架_创意_书籍

创建新书

• name：书名（必填）
• description：可选描述
• tags：可选标签

书架_创意_触觉

创建新章节

• book_id：图书ID（必填）
• name：章节名称（必填）
• description：可选描述
• tags：可选标签

故障排除

连接问题

如果Cursor无法连接到BookStack：

1. 验证BookStack是否正在运行： curl http://192.168.1.193:6875
2. 检查您的API令牌是否正确
3. 确保令牌具有足够的权限

权限问题

如果你收到403个错误：

• 您的API令牌可能缺少必要的权限
• 创建具有管理员或适当角色权限的新令牌

服务器未启动

如果Python服务器无法启动：

• 检查Python版本： python --version （必须为3.8+）
• 验证依赖关系： pip list | grep fastmcp
• 检查中的错误 .env 文件

发展

要使用更多工具扩展此服务器，请执行以下操作：

1. 添加装饰有新功能 @mcp.tool()
2. 使用 BookStackClient 用于API调用
3. 遵循现有工具的模式

例子：

@mcp.tool()
async def bookstack_custom_operation(param: str) -> str:
    """Your custom tool description"""
    client = get_client()
    result = await client.request("GET", f"endpoint/{param}")
    return str(result)

api参考

BookStack API文档：https://www.bookstackapp.com/docs/api/

许可证

这个项目是开源的，可以修改和使用。