GridStack

You run a GridStack MCP Server to expose GridStack’s API through the MCP protocol so you can control and automate dashboards, widgets, and layouts from MCP clients. This server enables you to initialize grids, add and manage widgets, handle layouts, and respond to events from remote tools and editors that communicate via MCP.

How to use

You connect to the MCP Server using an MCP client that supports stdio-based communication. The server accepts commands to initialize grids, manipulate widgets, save/load layouts, and configure responsive behavior. You will typically start the local server process and point your MCP client at the running instance, then issue tool calls to perform actions such as creating grids, adding widgets, resizing, moving, and saving layouts.

How to install

# Prerequisites
Node.js 18+
npm or yarn

# 1. Clone the project
git clone <repository-url>
cd gridstack-mcp-server

# 2. Install dependencies
yarn install
# or
npm install

# 3. Build the project
yarn build
# or
npm run build

Configuration and running

To run locally in development, build the server and start it so MCP clients can connect via stdio. You will typically start a process that runs the MCP server script and then configure your MCP client to launch or connect to that stdio channel.

The server can be wired into clients that support the MCP protocol. For example, you can configure clients to spawn the server using a node command that points to the built entry file, and you can also configure your editor/IDE integration to run the server in the same fashion.

Testing and debugging

Test basic MCP interactions by invoking the server with common tool endpoints. You can list tools, initialize a grid with options, and list resources to verify the server responds and the grid state can be retrieved.

• List tools
• Initialize a grid with options
• List resources

Available tools

gridstack_init

Initialize new GridStack instance with specified options.

gridstack_destroy

Destroy the current GridStack instance and clear resources.

gridstack_enable

Enable or disable grid interactions.

gridstack_add_grid

Create a new grid with given options and child widgets.

gridstack_add_widget

Add a new widget to the grid with position and size.

gridstack_remove_widget

Remove a widget from the grid.

gridstack_update_widget

Update properties of an existing widget.

gridstack_move_widget

Move a widget to a new position.

gridstack_resize_widget

Resize a widget.

gridstack_make_widget

Convert a DOM element into a grid widget.

gridstack_remove_all

Remove all widgets from the grid.

gridstack_compact

Compact the grid layout to minimize gaps.

gridstack_float

Toggle floating mode for widgets.

gridstack_column

Change the number of columns in the grid.

gridstack_cell_height

Update the height of a grid cell.

gridstack_margin

Update grid margins.

gridstack_batch_update

Batch multiple operations for performance.

gridstack_save

Save the current layout to JSON.

gridstack_load

Load a layout from JSON.

gridstack_get_grid_items

Retrieve all grid items.

gridstack_get_margin

Get current grid margins.

gridstack_get_column

Get the number of grid columns.

gridstack_get_float

Get the floating state.

gridstack_will_it_fit

Check if a widget fits in the target area.

gridstack_is_area_empty

Check if a grid area is empty.

gridstack_get_cell_height

Get the current cell height.

gridstack_get_cell_from_pixel

Convert pixel coordinates to grid cells.

gridstack_on

Add an event listener.

gridstack_off

Remove an event listener.

gridstack_set_responsive

Configure responsive breakpoints.