home / mcp / whkerdb mcp server

WhkerDB MCP Server

Provides access to WhkerDB capabilities for room management, note operations, annotations, PDFs, and images with real-time synchronization.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

You can run and integrate the WhkerDB MCP Server to enable AI assistants and third‑party apps to access full Shared PDF editor capabilities, including real-time collaboration, note management, annotations, and media handling through a consistent MCP interface.

How to use

You use an MCP client to connect to the WhkerDB MCP Server and perform actions such as creating rooms, managing notes, uploading PDFs and images, and annotating content. Start by launching the MCP server in stdio mode, then configure your client to point at the local server or the online endpoint. When connected, you can perform combined workflows like creating a room, adding documents, and applying annotations, with changes syncing in real time to all connected clients.

How to install

Prerequisites you need before installation: Node.js version 18 or newer, and a package manager such as pnpm (recommended) or npm/yarn. You also need access to a running WhkerDB server or an online service to connect to.

# Clone the MCP server repository
git clone https://github.com/A-Quark2005/whkerdb-mcp.git
cd whkerdb-mcp

# Install dependencies
pnpm install

# Build the project
pnpm build

Run the MCP server in stdio mode

After building, you can start the MCP server in stdio mode. Set the server URL environment variable if you want to point to a specific remote WhkerDB server, otherwise it defaults to the online service.

# Set the WhkerDB server URL (optional, defaults to https://share.whkerdb.top)
export WHKERDB_SERVER_URL=https://share.whkerdb.top

# Start the MCP server in stdio mode
pnpm start

Test with MCP Inspector

You can test the MCP interface using the MCP Inspector in stdio mode, which opens an interactive session against the local or remote server.

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

Configuration and integration

Configure client applications to connect to the MCP server by providing the server URL and the path to the MCP entry script when using local stdio mode. The WhkerDB MCP Server exposes capabilities for rooms, notes, annotations, PDFs, and images, and keeps all connected clients in sync via Socket.IO.

API and resources

The server exposes a suite of tools to manage rooms, notes, annotations, PDFs, and images. You can create and join rooms, browse and modify the note tree, add text or image annotations, upload PDFs, and manage media associated with a room. The system supports real-time synchronization to keep collaborators in sync.

Examples of common workflows

Example workflows include creating a new project room, adding a PDF document, and annotating pages, then sharing the room with teammates for live collaboration.

Security and notes

Ensure you use a trusted WhkerDB server URL and manage access to rooms carefully. Real-time synchronization is enabled via Socket.IO, so monitor connected clients and manage permissions accordingly.

Available tools

whkerdb_create_room

Create a new collaboration room.

whkerdb_join_room

Join a room by ID or invite code.

whkerdb_get_room_info

Retrieve information about a room.

whkerdb_list_rooms

List rooms you have joined.

whkerdb_export_snapshot

Export a snapshot of a room.

whkerdb_leave_room

Leave a room.

whkerdb_get_note_tree

Get the note tree structure for a room.

whkerdb_add_file

Add a file node to the note tree.

whkerdb_add_page

Add a page node under a file.

whkerdb_delete_node

Delete a node from the note tree.

whkerdb_move_node

Move a node within the tree.

whkerdb_update_node

Update node properties.

whkerdb_get_node

Get details of a node.

whkerdb_get_page_objects

Retrieve annotations and objects on a page.

whkerdb_add_text

Add a text annotation.

whkerdb_add_path

Add a path annotation (pen/highlighter).

whkerdb_add_image

Add an image annotation.

whkerdb_update_object

Update an annotation object.

whkerdb_delete_object

Delete an annotation object.

whkerdb_upload_pdf

Upload a PDF file.

whkerdb_list_pdfs

List PDFs in a room.

whkerdb_get_pdf_info

Get information about a PDF.

whkerdb_upload_image

Upload an image into a room.

whkerdb_list_images

List images in a room.