Boarderless Model Context Protocol (MCP) Server

A Model Context Protocol (MCP) server for Boarderless, allowing Ai agents (like Claude Desktop, Cursor, and Claude Code) to inspect and edit the live browser-resident canvas directly. Boarderless remains Local First: the browser owns the working canvas, and this server connects an agent to that visible local session rather than inventing a hidden cloud copy.

Looking for the app-wide map—canvas tools, image editing, slides, Ai Partner, persistence, plan boundaries, and the exact MCP subset? Ai agents connecting to this repository should parse the Boarderless Product & MCP Feature Catalog before proposing work. Connector distribution and OpenAI/Microsoft readiness are tracked in docs/connector_distribution_plan.md; the future OAuth 2.1/Streamable HTTP adapter design is in docs/oauth21_remote_adapter_plan.md; Joel's selected Option A browser bridge is specified in docs/remote_session_bridge_spec.md; Joel's operator path is in docs/connector_operator_runbook.md.

Rather than scraping pixels or guessing layouts from DOM selectors, agents communicate with a clean, typed spatial ledger.

⚡ Quick Start (TL;DR)

Step 1: Start the Interactive Configurator (Windows, Mac, or Linux) Run the installer to configure your environment and client settings:

• Windows (PowerShell):

  Set-ExecutionPolicy Bypass -Scope Process -Force; .\src\setup.ps1

• Mac / Linux (Terminal):

  chmod +x ./src/setup.sh && ./src/setup.sh

Step 2: Choose Option 1 (Standard Auto-Setup) The interactive installer will:

1. Explain permissions (browser connection, file access).

2. Install pure JavaScript dependencies automatically.

3. Register the MCP server in your Claude Desktop configuration.

4. Provide immediate copy-paste instructions for Cursor or Windsurf.

Related MCP server: Excalidraw MCP Server

Architecture Overview

+------------------+                   +--------------------+
|  Ai Agent Client |                   | Boarderless App    |
|  (Claude/Cursor) |                   | (Zustand + React)  |
+--------+---------+                   +---------+----------+
         |                                       ^
         | (Stdio JSON-RPC)                      | (window.boarderlessMcp)
         v                                       v
+------------------+  CDP / Puppeteer  +---------+----------+
|    MCP Server    +------------------>|  Chrome / Edge     |
| (Stdio Transport)|                   |  Debugging Port    |
+------------------+                   +--------------------+

1. Boarderless Web App: Exposes window.boarderlessMcp containing typed tool execution methods over Zustand state.

2. MCP Server (mcp-stdio-server.js): Connects to the browser via Chrome DevTools Protocol (CDP), maps incoming stdio messages to the browser runtime, and checks authentication. If the remote debugging port (9222) is closed, the server automatically scans and launches Chrome or Edge in remote-debugging mode.

3. Ai Agent: Connects as a client to the MCP server's stdio transport.

4. Workspace Board File: After every successful canvas mutation, the MCP server asks the browser persistence layer for the canonical schema-v2 snapshot and atomically writes <board-name>--<board-id>.bdrl.json into the configured local workspace.

One product, two different agent surfaces

• Ai Partner lives inside the Boarderless app. It interprets supported natural-language canvas requests through Gemini, OpenAI, Anthropic Claude, Z.AI/GLM, local models, or a custom OpenAI-compatible endpoint, and performs local per-image background removal.

• Boarderless MCP connects external agent clients to the running, human-visible canvas. It can inspect, measure, create supported text/shapes, mutate, delete, group, ungroup, reorder, undo, redo, export, and maintain durable .bdrl.json artifacts.

• MCP does not inherit the user's Google identity, grant itself Drive access, upload arbitrary local images into the canvas, or bypass plan restrictions. Those boundaries stay with the human and the app.

The complete app feature surface—including image editing, presentations, minimap, typography, exports, persistence, plan boundaries, Ai Partner, and MCP—is indexed in docs/features_catalog.md.

Always-saved .bdrl.json workflow

Agents must treat the board file as part of the task artifact, not as an optional final export:

1. Call get_board_workspace before canvas work.

2. If it is not the user's current project directory, call set_board_workspace with that absolute directory (or set BOARDERLESS_WORKSPACE_DIR in MCP configuration).

3. Use the normal mutation tools. Every successful create, mutate, delete, group, reorder, undo, or redo automatically refreshes the canonical .bdrl.json file.

4. Before handoff, call export_board_file and report its returned path. This explicit final flush makes the artifact requirement visible even if an earlier autosave warning occurred.

5. To resume work, place a schema-v2 .bdrl.json file in the workspace and call import_board_file with its filename. The backend validates containment and schema, imports it through Boarderless persistence, switches the live canvas to it, and refreshes autosave.

Board file reads and writes are restricted to the configured workspace. Filenames cannot contain directories or traversal segments. Writes use a same-directory temporary file followed by an atomic rename so interrupted writes do not leave half-valid JSON.

Prerequisites

1. Node.js (v18 or higher)

2. Supported OS & Browser: Windows 10/11 with a Chromium-based browser—Google Chrome, Brave Browser, Opera, or Microsoft Edge—uses the primary tested path. macOS and Linux use community fallback paths.

3. Boarderless Web App: Access via production at https://boarderless.app/canvas (default) or your local dev server if running one.

Note: This Model Context Protocol server is optimized specifically for Windows. Google Chrome, Brave Browser, Opera, and Microsoft Edge are all fully supported. macOS and Linux are supported as community fallbacks.

Getting Started

1. Launch Browser with Remote Debugging Enabled

To allow the MCP server to attach to your browser tab, you must start Chrome or Edge with debugging port 9222 active. The MCP server will automatically try to find and launch Chrome/Edge on port 9222 if it is not already running.

If you want to launch it manually, we provide pre-built launchers:

• Windows: Double-click ./launch-chrome-debugging.bat (or run it via cmd/PowerShell).

• macOS/Linux: Run chmod +x ./launch-chrome-debugging.sh && ./launch-chrome-debugging.sh.

Alternatively, launch manual instances: Windows (PowerShell):

& "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir="$env:LOCALAPPDATA\boarderless-mcp-profile" https://boarderless.app/canvas

macOS (Terminal):

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 --user-data-dir="$HOME/Library/Application Support/boarderless-mcp-profile" https://boarderless.app/canvas

Note: Make sure to sign in/authenticate Google OAuth on the canvas page.

2. Install & Setup (Seamless Installers)

We provide pre-built install scripts that automatically check for Node.js (offering to install it if missing), install all package dependencies, write the Claude Desktop configuration, and offer to launch debugging:

• Windows: Open PowerShell in this folder and run:

  Set-ExecutionPolicy Bypass -Scope Process -Force; .\src\setup.ps1

• macOS & Linux (Ubuntu): Open Terminal in this folder and run:

  chmod +x ./src/setup.sh && ./src/setup.sh

Alternatively, perform manual installation:

1. Run npm install.

2. Run npm run setup.

3. Run the Example

Verify your connection by running the test client, which queries the canvas state and moves the first element:

npm run example

Diagnosing Issues — get_server_status

Always call get_server_status first before attempting canvas operations.

It returns a structured JSON report with four health checks and actionable resolution steps for every failure:

{
  "status": "ok",
  "ready": true,
  "summary": "All systems operational. Ready to control Boarderless.",
  "checks": [
    { "check": "browser_port",    "passed": true,  "detail": "Chromium DevTools listening on http://127.0.0.1:9222" },
    { "check": "canvas_tab",      "passed": true,  "detail": "Active canvas tab: https://boarderless.app/canvas" },
    { "check": "mcp_bridge",      "passed": true,  "detail": "window.boarderlessMcp bridge is mounted and ready" },
    { "check": "authentication",  "passed": true,  "detail": "User is authenticated — canvas tools are available" }
  ],
  "runtime": {
    "platform": "win32",
    "node_version": "v22.3.0",
    "server_version": "0.1.26",
    "app_url": "https://boarderless.app/canvas",
    "browser_url": "http://127.0.0.1:9222",
    "started_at": "2026-06-16T19:07:00.000Z",
    "tool_calls": 1,
    "tool_errors": {}
  },
  "next_steps": ["Call get_board_state to inspect the current canvas."]
}

When something fails, each check includes a resolution field with exact fix steps:

{ "check": "authentication", "passed": false,
  "resolution": "Sign in with Google at https://boarderless.app/canvas. Canvas tools require an active Boarderless session." }

Structured Error Responses

Every tool returns a structured JSON error object — never a raw exception string. Agents can parse error_code to decide next steps programmatically.

Error shape:

{
  "status": "error",
  "error_code": "AUTH_REQUIRED",
  "message": "You must be signed in to Boarderless to use canvas tools.",
  "resolution": "1. Open https://boarderless.app/canvas ...\n2. Sign in...",
  "server": "boarderless-mcp-bridge",
  "version": "0.1.26",
  "timestamp": "2026-06-16T19:07:00.000Z"
}

Environment Variables (Full Reference)

All configuration uses environment variables — no hardcoded paths, no user-specific assumptions.

Default profile directories (resolved from OS env vars, never hardcoded):

• Windows: %LOCALAPPDATA%\boarderless-mcp-profile

• macOS: ~/Library/Application Support/boarderless-mcp-profile

• Linux: ~/.boarderless-mcp-profile

Tool API Specifications

get_server_status (always call this first)

Returns a full diagnostic report. Input: none. See Diagnosing Issues above.

get_board_state

Returns the canvas as a structured, render-ordered JSON ledger.

• Input: None ({})

• Output:

  {
    "schema": "boarderless.boardSnapshot.v1",
    "generatedAt": "2026-06-16T19:00:00.000Z",
    "objectCount": 3,
    "objects": [
      {
        "id": "rect-1",
        "objectKind": "shape",
        "objectType": "rect",
        "x": 20, "y": 20,
        "rawWidth": 80, "rawHeight": 50,
        "fill": "#ff0000", "stroke": "#ff0000",
        "strokeWidth": 4, "opacity": 1, "rotation": 0
      }
    ]
  }

mutate_object

Modifies coordinates or style properties of a canvas object. Writes to the undo stack.

• Required: id (string)

• Optional mutable fields: x, y, width, height, rotation, opacity, fill, stroke, strokeWidth, text, fontSize, fontFamily, align, cornerRadius, edgeFeather, points, scaleX, scaleY

remix_style

Applies one canonical Boarderless palette to selected shape/text Objects—or explicitly to the whole board—as one undoable history step. Images remain unchanged.

• Required: paletteId — "boarderless" | "midnight" | "sunroom" | "editorial" | "earthbound"

• Optional: scope — "selection" (default) | "board"; ids — explicit selection-scope Object IDs

calculate_export_bounds

Returns the collective bounding box of all active objects.

• Input: None ({})

• Output: { bounds: { x, y, width, height, left, top, right, bottom } }

create_object

Create a new object (text or shape: rect, ellipse, triangle, arrow) on the canvas.

• Required: type — "text" | "rect" | "ellipse" | "triangle" | "arrow"

• Optional: x (number), y (number), width (number), height (number), text (string), fill (string), stroke (string), strokeWidth (number)

delete_objects

Delete one or more objects by their IDs from the canvas.

• Required: ids (array of strings)

history_undo

Undo the last action on the canvas.

• Input: None ({})

history_redo

Redo the next action in the history queue on the canvas.

• Input: None ({})

group_objects

Group multiple canvas objects under a unique groupId.

• Required: ids (array of strings)

ungroup_objects

Ungroup objects belonging to a specific groupId.

• Required: groupId (string)

reorder_object

Reorder z-index layering of an object (bring to front, send to back, forward, backward).

• Required: id (string), action — "front" | "back" | "forward" | "backward"

get_board_workspace

Returns the active filesystem directory, autosave state, and filename pattern. Agents should call this before their first canvas mutation.

set_board_workspace

Sets the absolute project directory used for board artifacts. The directory is created when necessary.

• Required: directory (absolute path)

export_board_file

Flushes the browser's current board and atomically writes its complete schema-v2 snapshot, including JSON-safe image assets.

• Optional: filename — a single filename ending in .bdrl.json; omitting it uses the stable autosave name.

import_board_file

Reads, validates, imports, and opens a board from the configured workspace.

• Required: filename — a single .bdrl.json filename in the workspace

export_board

Exports the current canvas to PNG, PDF, or SVG.

• Required: format — "png" | "pdf" | "svg"

• Optional: mode — "canvas" (default) | "selection", filename — output name override

• Note: SVG and PDF require a Pro plan. The error response will indicate this clearly.

graduation_rename_photos

Renames photo files in a local directory to sequential format. No browser required.

• Required: seniorsDir (absolute path), mode ("sequential" | "gap_fill")

graduation_standardize_images

Converts progressive JPEGs and HEIC files to baseline RGB JPEGs. No browser required.

• Required: seniorsDir (absolute path)

Connecting to AI Clients

Claude Desktop

Add to %APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS).

{
  "mcpServers": {
    "boarderless": {
      "command": "node",
      "args": ["/absolute/path/to/boarderless.app_MCP/src/mcp-stdio-server.js"],
      "env": {
        "BOARDERLESS_MCP_APP_URL": "https://boarderless.app/canvas",
        "BOARDERLESS_MCP_BROWSER_URL": "http://127.0.0.1:9222",
        "BOARDERLESS_WORKSPACE_DIR": "C:\\absolute\\path\\to\\your\\project"
      }
    }
  }
}

Running npm run setup will write this automatically.

Hermes / OpenClaw (Local AI Gateway)

Add to your openclaw.json under mcp.servers:

"mcp": {
  "servers": {
    "boarderless": {
      "command": "node",
      "args": ["/absolute/path/to/boarderless.app_MCP/src/mcp-stdio-server.js"],
      "env": {
        "BOARDERLESS_MCP_APP_URL": "https://boarderless.app/canvas",
        "BOARDERLESS_MCP_BROWSER_URL": "http://127.0.0.1:9222",
        "BOARDERLESS_WORKSPACE_DIR": "/absolute/path/to/your/project"
      }
    }
  }
}

Cursor / Windsurf

See the mcp-config.json file generated by npm run setup for the exact config block to paste.

VS Code / GitHub Copilot and connector directories

VS Code / GitHub Copilot can use Boarderless as a local stdio MCP server through .vscode/mcp.json.

Hosted OpenAI and Microsoft status

Joel selected Option A: browser-mediated visible-session bridge for future remote readiness. Boarderless will not host user data or server-side boards; user data stays user-managed, user-owned, and user-controlled. See docs/remote_session_bridge_spec.md.

@boarderless/mcp-server v0.1.26 is not a hosted ChatGPT App or Microsoft Copilot Studio connector. npm distributes the local stdio connector only.

• OpenAI outstanding: public HTTPS MCP resource server, OAuth 2.1 authorization-code flow with PKCE, protected-resource and authorization-server discovery metadata, ChatGPT client registration/callback, scoped token validation, and a secure relay from the hosted service to the user's visible Boarderless browser session.

• Microsoft outstanding: public Streamable HTTP MCP endpoint, OAuth 2.0 through DCR/discovery or manual client registration, Copilot callback registration, scoped token validation/refresh/revocation, and the same secure remote-to-visible-canvas relay.

• Shared outstanding: remote-safe tool policy, explicit controls for writes, rate limits, audit logging, privacy/retention rules, secret management, security review, end-to-end tests, and platform submission/review.

OAuth identifies and authorizes a user; it does not make a cloud service capable of reaching that user's localhost browser or Chrome DevTools port. The selected path is a user-approved outbound browser bridge bound to the visible tab/canvas, not a hidden cloud board. See the complete hosted-connector checklists, the docs-only remote adapter plan, the browser bridge spec, and the operator gates.

Privacy Policy

Boarderless MCP is a local connector. The full Boarderless privacy policy is published at https://boarderless.app/privacy (also declared in manifest.json privacy_policies).

Summary of how this MCP server handles data:

• Data collection: The server itself collects no analytics and sends no telemetry. It reads canvas state from your own signed-in, human-visible Boarderless browser tab via the Chrome DevTools Protocol on 127.0.0.1:9222.

• Usage and storage: Board snapshots (.bdrl.json) and exports are written only to the local workspace directory you configure. Nothing is uploaded to Boarderless servers by this MCP server.

• Third-party sharing: None. The server communicates only with your local browser and the Boarderless canvas page you are signed into. It never inherits your Google identity or Google Drive access.

• Data retention: Local board files remain on your machine under your control; delete them at any time. The server keeps no databases, queues, or server-side copies.

• Contact: Questions or concerns — open an issue at https://github.com/CrackenReleased/boarderless.app_MCP/issues or use the contact channel listed at https://boarderless.app/privacy.

Contributing

This MCP server is open source under the Apache 2.0 license. Contributions are welcome!

• Bug reports: Open an issue describing the error_code you received and your get_server_status output.

• New tools: Tools should be added as siloed handlers in mcp-stdio-server.js with structured makeError / makeSuccess responses. Every new tool must have a corresponding regression test.

• Platform support: If your browser or OS isn't detected, open a PR adding its path to getBrowserCandidates() — all paths must use OS env vars, never hardcoded usernames.

Production release synchronization

After the initial npm publication is approved, every production MCP version must be delivered to both GitHub and npm under the same version number. A production release is not complete until npm test and npm publish --dry-run --access public pass, the Git commit is pushed, npm publish --access public succeeds, and npm view @boarderless/mcp-server version returns that exact version. Documentation-only commits that do not change the MCP package version do not require an npm publication.

License

Licensed under the Apache License, Version 2.0. See LICENSE for details.