How do I use WhkerDB MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@WhkerDB MCP Server Create a room named 'Project Alpha' and upload the proposal.pdf file." That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

WhkerDB MCP Server

npm version TypeScript MCP

讲了么（WhkerDB）的 MCP（Model Context Protocol）服务器实现，为 AI 助手和第三方应用提供讲了么共享 PDF 编辑器的完整功能访问能力。

✨ 特性

🏠 房间管理 - 创建、加入、管理协作房间
📝 笔记树操作 - 完整的文件树结构管理
🎨 标注功能 - 支持文本、路径、图片等多种标注类型
📄 PDF 处理 - 上传、查看和管理 PDF 文件
🖼️ 图片管理 - 图片上传和列表功能
🔄 实时同步 - 基于 Socket.IO 的实时数据同步
🔌 多平台支持 - 支持 Claude Desktop、Claude Code、CodeX 等

📋 目录

WhkerDB MCP Server

🚀 安装

前置要求

Node.js >= 18
pnpm (推荐) 或 npm/yarn
运行中的讲了么（WhkerDB）服务器或访问在线服务

安装步骤

# 克隆仓库
git clone https://github.com/A-Quark2005/whkerdb-mcp.git
cd whkerdb-mcp

# 安装依赖
pnpm install

# 构建项目
pnpm build

🎯 快速开始

命令行模式（stdio）

# 设置服务器地址（可选，默认 https://share.whkerdb.top）
export WHKERDB_SERVER_URL=https://share.whkerdb.top

# 启动 MCP 服务器
pnpm start

使用 MCP Inspector 测试

npx @modelcontextprotocol/inspector stdio node dist/index.js

🔌 集成指南

Claude Desktop

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

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

{
  "mcpServers": {
    "whkerdb": {
      "command": "node",
      "args": ["/absolute/path/to/whkerdb-mcp/dist/index.js"],
      "env": {
        "WHKERDB_SERVER_URL": "https://share.whkerdb.top"
      }
    }
  }
}

Claude Code (CLI)

使用命令行添加项目级配置（配置会写入项目根目录的 .mcp.json）：

# Windows PowerShell
claude mcp add -s project whkerdb node C:\path\to\whkerdb-mcp\dist\index.js -e WHKERDB_SERVER_URL=https://share.whkerdb.top

# macOS/Linux
claude mcp add -s project whkerdb node /path/to/whkerdb-mcp/dist/index.js -e WHKERDB_SERVER_URL=https://share.whkerdb.top

CodeX (Codex CLI)

命令行方式：

# Windows PowerShell
codex mcp add whkerdb --env WHKERDB_SERVER_URL=https://share.whkerdb.top -- node C:\path\to\whkerdb-mcp\dist\index.js

# macOS/Linux
codex mcp add whkerdb --env WHKERDB_SERVER_URL=https://share.whkerdb.top -- node /path/to/whkerdb-mcp/dist/index.js

配置文件方式（~/.codex/config.toml）：

[mcp_servers.whkerdb]
command = "node"
args = ['/path/to/whkerdb-mcp/dist/index.js']

[mcp_servers.whkerdb.env]
WHKERDB_SERVER_URL = "https://share.whkerdb.top"

MCP Inspector 测试

使用 MCP Inspector 进行交互式测试和调试：

npx @modelcontextprotocol/inspector stdio node dist/index.js

📚 API 文档

工具列表

房间管理

工具	描述
`whkerdb_create_room`	创建新房间
`whkerdb_join_room`	加入房间（支持房间 ID 或邀请码）
`whkerdb_get_room_info`	获取房间信息
`whkerdb_list_rooms`	列出已加入的房间
`whkerdb_export_snapshot`	导出房间快照
`whkerdb_leave_room`	离开房间

笔记树操作

工具	描述
`whkerdb_get_note_tree`	获取笔记树结构
`whkerdb_add_file`	添加文件节点
`whkerdb_add_page`	添加页面节点
`whkerdb_delete_node`	删除节点
`whkerdb_move_node`	移动节点
`whkerdb_update_node`	更新节点属性
`whkerdb_get_node`	获取节点详情

标注对象

工具	描述
`whkerdb_get_page_objects`	获取页面对象
`whkerdb_add_text`	添加文本标注
`whkerdb_add_path`	添加路径（画笔/高亮笔）
`whkerdb_add_image`	添加图片
`whkerdb_update_object`	更新对象属性
`whkerdb_delete_object`	删除对象

PDF 操作

工具	描述
`whkerdb_upload_pdf`	上传 PDF 文件
`whkerdb_list_pdfs`	列出房间内 PDF
`whkerdb_get_pdf_info`	获取 PDF 信息

图片操作

工具	描述
`whkerdb_upload_image`	上传图片
`whkerdb_list_images`	列出房间内图片

资源 URI

说明：带 {} 的为资源模板（resources/templates/list）；加入房间后也可以通过 resources/list 获取当前房间的实际资源 URI。

URI	描述
`whkerdb://rooms`	房间列表
`whkerdb://rooms/{roomId}`	房间详情
`whkerdb://rooms/{roomId}/tree`	笔记树结构
`whkerdb://rooms/{roomId}/pages/{nodeId}`	页面内容
`whkerdb://pdfs/{pdfId}/info`	PDF 信息

💡 使用示例

示例 1: 创建房间并添加内容

// 1. 创建房间
whkerdb_create_room({ name: "我的项目" })

// 2. 加入房间
whkerdb_join_room({ roomId: "room-id" })

// 3. 创建文件节点
whkerdb_add_file({ 
  parentId: "root", 
  name: "文档.pdf" 
})

// 4. 添加页面
whkerdb_add_page({ 
  parentId: "file-id", 
  name: "第1页" 
})

// 5. 添加文本标注
whkerdb_add_text({
  pageId: "page-id",
  content: "这是重要注释",
  x: 100,
  y: 200
})

示例 2: 上传 PDF 并标注

// 1. 加入房间
whkerdb_join_room({ roomId: "room-id" })

// 2. 上传 PDF（自动创建节点）
whkerdb_upload_pdf({
  filePath: "/path/to/document.pdf",
  name: "文档.pdf"
})

// 3. 查看树结构
whkerdb_get_note_tree({ roomId: "room-id" })

// 4. 在页面上添加标注
whkerdb_add_text({
  pageId: "page-id",
  content: "需要重点注意",
  x: 150,
  y: 300
})

🛠️ 开发

项目结构

whkerdb-mcp/
├── src/
│   ├── client/          # 讲了么MCP客户端实现
│   ├── resources/       # MCP 资源定义
│   ├── tools/           # MCP 工具实现
│   │   ├── roomTools.ts
│   │   ├── treeTools.ts
│   │   ├── objectTools.ts
│   │   ├── pdfTools.ts
│   │   └── imageTools.ts
│   ├── server.ts        # MCP 服务器配置
│   └── index.ts         # 入口文件
├── dist/                # 编译输出
├── bin/                 # 可执行文件
└── package.json

开发命令

# 开发模式（监听文件变化）
pnpm dev

# 构建项目
pnpm build

# 启动服务器
pnpm start

# 启动 stdio 模式
pnpm start:stdio

技术栈

TypeScript - 类型安全
@modelcontextprotocol/sdk - MCP 协议实现
Socket.IO Client - 实时通信
tsup - 构建工具

⚙️ 环境变量

变量	描述	默认值
`WHKERDB_SERVER_URL`	讲了么（WhkerDB）服务器地址	`https://share.whkerdb.top`

⚠️ 注意事项

服务器要求: 使用工具前需要确保讲了么（WhkerDB）服务器可访问（默认使用在线服务 https://share.whkerdb.top，也可配置本地服务器）
房间上下文: 大部分工具需要先加入房间（使用 whkerdb_join_room）
文件上传: 支持本地文件路径或 Base64 编码
实时同步: 所有操作会通过 Socket.IO 实时同步到其他连接的客户端
路径配置: 在配置文件中使用绝对路径，避免相对路径问题

🤝 贡献

欢迎提交 Issue 和 Pull Request！

WhkerDB MCP Server

WhkerDB MCP Server

✨ 特性

📋 目录

🚀 安装

前置要求

安装步骤

🎯 快速开始

命令行模式（stdio）

使用 MCP Inspector 测试

🔌 集成指南

Claude Desktop

Claude Code (CLI)

CodeX (Codex CLI)

MCP Inspector 测试

📚 API 文档

工具列表

房间管理

笔记树操作

标注对象

PDF 操作

图片操作

资源 URI

💡 使用示例

示例 1: 创建房间并添加内容

示例 2: 上传 PDF 并标注

🛠️ 开发

项目结构

开发命令

技术栈

⚙️ 环境变量

⚠️ 注意事项

🤝 贡献

🔗 相关链接

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API