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 |
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 documentationgridstack://examples/basic- Basic GridStack implementationgridstack://examples/responsive- Responsive grid examplegridstack://examples/react- React integrationgridstack://examples/vue- Vue integrationgridstack://templates/dashboard- Dashboard templategridstack://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
- 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! 🎯