Skip to main content
Glama

GridStack MCP Server

GridStack MCP Server

A comprehensive Model Context Protocol (MCP) server for GridStack.js - the powerful drag-and-drop grid layout library. This server provides complete access to GridStack's API through MCP tools and resources, making it easy to build dynamic dashboard layouts, responsive grids, and interactive widget systems.

πŸš€ Features

Core GridStack Operations

  • Grid Management: Initialize, destroy, enable/disable grids

  • Widget Operations: Add, remove, update, move, resize widgets

  • Layout Control: Compact, float mode, column management

  • Responsive Design: Breakpoint configuration and responsive layouts

  • Serialization: Save and load grid layouts to/from JSON

  • Event Handling: Complete event system for grid interactions

Developer Experience

  • 26+ Tools: Comprehensive coverage of GridStack API

  • Rich Resources: Examples, templates, and documentation

  • Framework Integration: React, Vue, Angular examples

  • CSS Support: Tailwind CSS and CSS modules integration

  • Type Safety: Full TypeScript support with detailed schemas

πŸ“¦ Installation

Prerequisites

  • Node.js 18+

  • npm or yarn

Setup

  1. Clone the repository:

git clone <repository-url> cd gridstack-mcp-server
  1. Install dependencies:

yarn install # or npm install
  1. Build the project:

yarn build # or npm run build

πŸƒβ€β™‚οΈ Running the Server

Local Development

# Build and start the server yarn build && yarn start # Development mode with auto-rebuild yarn dev

MCP Client Integration

The server runs on stdio and follows the MCP protocol. Here's how to integrate it with different MCP clients:

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{ "mcpServers": { "gridstack": { "command": "node", "args": ["/path/to/gridstack-mcp-server/dist/index.js"] } } }

Cursor/VSCode Integration

{ "mcp.servers": { "gridstack": { "command": "node", "args": ["./dist/index.js"], "cwd": "/path/to/gridstack-mcp-server" } } }

Testing the Server

Test with basic MCP commands:

# List available tools echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | node dist/index.js # Initialize a grid echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": "gridstack_init", "arguments": {"options": {"column": 12, "cellHeight": "auto"}}}}' | node dist/index.js # List resources echo '{"jsonrpc": "2.0", "id": 1, "method": "resources/list"}' | node dist/index.js

πŸ›  Available Tools

Grid Management

Tool

Description

gridstack_init

Initialize new GridStack instance

gridstack_destroy

Destroy grid instance

gridstack_enable

Enable/disable grid interactions

gridstack_add_grid

Create grid with options and children

Widget Operations

Tool

Description

gridstack_add_widget

Add new widget to grid

gridstack_remove_widget

Remove widget from grid

gridstack_update_widget

Update widget properties

gridstack_move_widget

Move widget to new position

gridstack_resize_widget

Resize widget dimensions

gridstack_make_widget

Convert DOM element to widget

gridstack_remove_all

Remove all widgets

Layout Management

Tool

Description

gridstack_compact

Compact grid layout

gridstack_float

Enable/disable floating mode

gridstack_column

Change number of columns

gridstack_cell_height

Update cell height

gridstack_margin

Update grid margins

gridstack_batch_update

Batch multiple operations

Data & State

Tool

Description

gridstack_save

Save layout to JSON

gridstack_load

Load layout from JSON

gridstack_get_grid_items

Get all grid items

gridstack_get_margin

Get current margins

gridstack_get_column

Get column count

gridstack_get_float

Get float state

Utilities

Tool

Description

gridstack_will_it_fit

Check if widget fits

gridstack_is_area_empty

Check if area is empty

gridstack_get_cell_height

Get current cell height

gridstack_get_cell_from_pixel

Convert pixels to grid cells

Events

Tool

Description

gridstack_on

Add event listener

gridstack_off

Remove event listener

Responsive

Tool

Description

gridstack_set_responsive

Configure breakpoints

πŸ“š Resources

The server provides several built-in resources:

  • gridstack://documentation/api - Complete API documentation

  • gridstack://examples/basic - Basic GridStack implementation

  • gridstack://examples/responsive - Responsive grid example

  • gridstack://examples/react - React integration

  • gridstack://examples/vue - Vue integration

  • gridstack://templates/dashboard - Dashboard template

  • gridstack://css/custom - Custom CSS examples

πŸ’‘ Usage Examples

Basic Grid Initialization

// Initialize a 12-column grid with auto height const grid = GridStack.init({ column: 12, cellHeight: "auto", margin: 10, float: false, });

Adding Widgets

// Add a widget with specific position and size grid.addWidget({ x: 0, y: 0, w: 3, h: 2, content: '<div class="my-widget">Content</div>', id: "widget1", });

Responsive Configuration

// Set up responsive breakpoints grid.setResponsive([ { w: 768, c: 1 }, // Mobile: 1 column { w: 992, c: 6 }, // Tablet: 6 columns { w: 1200, c: 12 }, // Desktop: 12 columns ]);

Save/Load Layout

// Save current layout const layout = grid.save(true); localStorage.setItem("dashboard-layout", JSON.stringify(layout)); // Load saved layout const savedLayout = JSON.parse(localStorage.getItem("dashboard-layout")); grid.load(savedLayout);

🎨 CSS Framework Support

Tailwind CSS Integration

The server includes comprehensive Tailwind CSS support for modern, utility-first styling:

Installation

# Install Tailwind CSS npm install -D tailwindcss @tailwindcss/forms @tailwindcss/typography npx tailwindcss init

Tailwind Configuration

// tailwind.config.js module.exports = { content: ["./src/**/*.{html,js,ts,jsx,tsx}"], theme: { extend: { gridTemplateColumns: { "gs-1": "repeat(1, minmax(0, 1fr))", "gs-2": "repeat(2, minmax(0, 1fr))", "gs-3": "repeat(3, minmax(0, 1fr))", "gs-4": "repeat(4, minmax(0, 1fr))", "gs-5": "repeat(5, minmax(0, 1fr))", "gs-6": "repeat(6, minmax(0, 1fr))", "gs-7": "repeat(7, minmax(0, 1fr))", "gs-8": "repeat(8, minmax(0, 1fr))", "gs-9": "repeat(9, minmax(0, 1fr))", "gs-10": "repeat(10, minmax(0, 1fr))", "gs-11": "repeat(11, minmax(0, 1fr))", "gs-12": "repeat(12, minmax(0, 1fr))", }, }, }, plugins: [], };

Tailwind GridStack Styles

/* Custom GridStack + Tailwind integration */ .grid-stack { @apply relative; } .grid-stack-item { @apply absolute transition-all duration-200 ease-in-out; } .grid-stack-item-content { @apply h-full w-full rounded-lg border border-gray-200 bg-white p-4 shadow-sm hover:shadow-md; } .grid-stack-item-content.ui-draggable-dragging { @apply shadow-lg ring-2 ring-blue-500 ring-opacity-50; } .grid-stack-item-content.ui-resizable-resizing { @apply shadow-lg ring-2 ring-green-500 ring-opacity-50; } /* Responsive grid utilities */ .grid-stack-1 { @apply grid-cols-gs-1; } .grid-stack-2 { @apply grid-cols-gs-2; } .grid-stack-3 { @apply grid-cols-gs-3; } .grid-stack-4 { @apply grid-cols-gs-4; } .grid-stack-5 { @apply grid-cols-gs-5; } .grid-stack-6 { @apply grid-cols-gs-6; } .grid-stack-7 { @apply grid-cols-gs-7; } .grid-stack-8 { @apply grid-cols-gs-8; } .grid-stack-9 { @apply grid-cols-gs-9; } .grid-stack-10 { @apply grid-cols-gs-10; } .grid-stack-11 { @apply grid-cols-gs-11; } .grid-stack-12 { @apply grid-cols-gs-12; }

Tailwind Widget Components

<!-- Modern Dashboard Widget --> <div class="grid-stack-item" gs-x="0" gs-y="0" gs-w="4" gs-h="3"> <div class="grid-stack-item-content bg-gradient-to-br from-blue-50 to-indigo-100 border-indigo-200" > <div class="flex items-center justify-between mb-4"> <h3 class="text-lg font-semibold text-gray-900">Sales Overview</h3> <div class="flex space-x-2"> <button class="p-1 text-gray-400 hover:text-gray-600"> <svg class="w-4 h-4" fill="currentColor" viewBox="0 0 20 20"> <path d="M10 6a2 2 0 110-4 2 2 0 010 4zM10 12a2 2 0 110-4 2 2 0 010 4zM10 18a2 2 0 110-4 2 2 0 010 4z" /> </svg> </button> </div> </div> <div class="space-y-3"> <div class="flex justify-between items-center"> <span class="text-sm text-gray-600">This Month</span> <span class="text-2xl font-bold text-indigo-600">$24,500</span> </div> <div class="w-full bg-gray-200 rounded-full h-2"> <div class="bg-indigo-600 h-2 rounded-full" style="width: 75%"></div> </div> <p class="text-sm text-green-600">β†— +12% from last month</p> </div> </div> </div>

CSS Modules Integration

For component-scoped styling, the server supports CSS Modules:

CSS Module Example

/* Widget.module.css */ .widget { background: linear-gradient(135deg, #667eea 0%, #764ba2 100%); border-radius: 12px; padding: 1.5rem; color: white; box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1); transition: transform 0.2s ease-in-out; } .widget:hover { transform: translateY(-2px); box-shadow: 0 8px 15px rgba(0, 0, 0, 0.2); } .widgetHeader { display: flex; justify-content: space-between; align-items: center; margin-bottom: 1rem; padding-bottom: 0.5rem; border-bottom: 1px solid rgba(255, 255, 255, 0.2); } .widgetTitle { font-size: 1.125rem; font-weight: 600; margin: 0; } .widgetValue { font-size: 2rem; font-weight: 700; margin: 0.5rem 0; } .widgetChart { flex: 1; background: rgba(255, 255, 255, 0.1); border-radius: 8px; display: flex; align-items: center; justify-content: center; min-height: 120px; }

React Component with CSS Modules

// Widget.jsx import styles from "./Widget.module.css"; const Widget = ({ title, value, change, children }) => { return ( <div className="grid-stack-item" gs-w="3" gs-h="2"> <div className={`grid-stack-item-content ${styles.widget}`}> <div className={styles.widgetHeader}> <h3 className={styles.widgetTitle}>{title}</h3> </div> <div className={styles.widgetValue}>{value}</div> {change && <p className={styles.widgetChange}>{change}</p>} {children && <div className={styles.widgetChart}>{children}</div>} </div> </div> ); };

πŸ”§ Advanced Configuration

Custom Widget Types

// Define custom widget templates const widgetTemplates = { chart: { w: 4, h: 3, content: '<div class="chart-widget">Chart Content</div>', minW: 2, minH: 2, }, kpi: { w: 2, h: 2, content: '<div class="kpi-widget">KPI Content</div>', noResize: true, }, }; // Use templates grid.addWidget(widgetTemplates.chart);

Event Handling

// Listen to grid events grid.on("change", (event, items) => { console.log("Layout changed:", items); // Auto-save layout localStorage.setItem("layout", JSON.stringify(grid.save())); }); grid.on("added", (event, items) => { console.log("Widget added:", items); }); grid.on("removed", (event, items) => { console.log("Widget removed:", items); });

Performance Optimization

// Batch multiple operations grid.batchUpdate(true); grid.addWidget(widget1); grid.addWidget(widget2); grid.addWidget(widget3); grid.batchUpdate(false); // Triggers single 'change' event

πŸš€ Framework Integration

React Hook

import { useEffect, useRef, useState } from "react"; import { GridStack } from "gridstack"; export const useGridStack = (options = {}) => { const gridRef = useRef(null); const [grid, setGrid] = useState(null); useEffect(() => { if (gridRef.current) { const gridInstance = GridStack.init(options, gridRef.current); setGrid(gridInstance); return () => gridInstance.destroy(); } }, []); return { gridRef, grid }; };

Vue Composable

// useGridStack.js import { ref, onMounted, onUnmounted } from "vue"; import { GridStack } from "gridstack"; export function useGridStack(options = {}) { const gridRef = ref(null); const grid = ref(null); onMounted(() => { if (gridRef.value) { grid.value = GridStack.init(options, gridRef.value); } }); onUnmounted(() => { grid.value?.destroy(); }); return { gridRef, grid }; }

πŸ“– API Reference

Tool Parameters

Each tool accepts specific parameters. Here are the most commonly used:

Widget Configuration

interface GridStackWidget { id?: string | number; x?: number; // X position (0-based) y?: number; // Y position (0-based) w?: number; // Width in columns h?: number; // Height in rows minW?: number; // Minimum width maxW?: number; // Maximum width minH?: number; // Minimum height maxH?: number; // Maximum height locked?: boolean; // Lock position/size noResize?: boolean; // Disable resizing noMove?: boolean; // Disable moving content?: string; // HTML content }

Grid Options

interface GridStackOptions { column?: number; // Number of columns (default: 12) cellHeight?: number | string; // Cell height ('auto', px, etc.) margin?: number | string; // Gap between items float?: boolean; // Enable floating widgets disableDrag?: boolean; // Disable dragging disableResize?: boolean; // Disable resizing animate?: boolean; // Enable animations acceptWidgets?: boolean; // Accept external widgets }

🀝 Contributing

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -m 'Add some amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. Open a Pull Request

πŸ“„ License

This project is licensed under the MIT License - see the LICENSE file for details.

πŸ™ Acknowledgments

πŸ“ž Support


Happy Grid Building! 🎯

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/raghavsharma-simpplr/gridstack-mcp-server'

If you have feedback or need assistance with the MCP directory API, please join our Discord server