Halaman MCP Server

Model Context Protocol (MCP) companion server for Halaman Studio. It lets AI clients such as Claude Desktop, Cursor, and VS Code agents inspect and edit the live Halaman canvas through a local WebSocket bridge on port 9001.

This package is the standalone Node.js distribution of the MCP workflow used by the current Halaman project. It reflects the current app model:

• The browser editor connects automatically to ws://127.0.0.1:9001.
• The default blank canvas is 1206 x 760.
• Halaman supports multiple canvas presets: square, portrait, widescreen, story, and custom.
• Built-in templates live in the app as JSON layouts and intentionally set text autoWidth: false so layouts wrap predictably.

Quick Start

Run directly with npx

npx -y halaman-mcp

Claude Desktop config

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

{
  "mcpServers": {
    "halaman-mcp": {
      "command": "npx",
      "args": ["-y", "halaman-mcp"]
    }
  }
}

Local Development

git clone <your-halaman-mcp-repo>
cd halaman-mcp
npm install
npm run build
npm run start

Tools

• get_canvas_state: Return the current live CardState JSON from the browser editor.
• add_element: Add a text, shape, link, gaming, crypto, QR, or barcode element.
• update_element: Update position, size, z-index, rotation, or properties on an existing element.
• delete_element: Remove an element by ID.
• set_canvas_background: Set a solid or gradient canvas background plus border settings.
• align_element: Align an element to the canvas or another element.
• get_card_preview: Render the current card as a PNG.
• clear_canvas: Reset the canvas to Halaman's blank starter card.
• get_template_catalog: Return the current built-in Halaman template catalog and format notes.

Resources

• halaman-app://docs/alignment-guide
• halaman-app://docs/elements-guide
• halaman-app://docs/templates-guide

Notes

• A Halaman editor tab must be open and connected, or live-editing tools will return an error.
• set_canvas_background currently drives the live MCP bridge for solid and gradient backgrounds. The full app data model also supports image backgrounds.
• Grouped elements exist in the editor and published renderer, but MCP creation tools currently target leaf elements instead of creating groups directly.