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

Clone the repository:

git clone <repository-url>
cd gridstack-mcp-server

Install dependencies:

yarn install
# or
npm install

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

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;
}

<!-- 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

// 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:

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

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

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

🙏 Acknowledgments

GridStack.js - The amazing grid layout library
Model Context Protocol - The protocol this server implements
Anthropic - For the MCP specification and Claude integration

📞 Support

Happy Grid Building! 🎯

This server cannot be installed

security - not tested

license - not found

quality - not tested

How are these scores calculated?

local-only server

The server can only run on the client's local machine because it depends on local resources.

Provides comprehensive access to GridStack.js functionality for building dynamic dashboard layouts and responsive drag-and-drop grid systems. Includes 26+ tools for widget management, layout control, and serialization with support for React, Vue, and modern CSS frameworks.