gauravsaini/gluestack-ui-mcp-server

Gluestack UI MCP Server 📱

📱 The definitive MCP server for React Native development with Gluestack UI - Build universal apps with AI assistance!

This Model Context Protocol (MCP) server provides AI assistants with comprehensive access to Gluestack UI - the premier React Native-first component library that delivers true cross-platform experiences. Whether you're building for iOS, Android, or the web, this server intelligently provides components, source code, and examples optimized for React Native development workflows.

Key Features

📱 React Native-First Development

• 70+ React Native Components: Production-ready components optimized for mobile-first development
• Universal Platform Support: Single codebase runs on iOS, Android, and Web seamlessly
• Expo Integration: Perfect compatibility with Expo workflows and managed builds
• React Native Navigation: Built-in support for stack, tab, and drawer navigation patterns
• Platform-Specific Optimizations: Components automatically adapt to iOS and Android design guidelines

🎨 Multi-Variant Architecture for React Native

Go beyond basic styling with variants designed for different React Native use cases:

• 🎨 NativeWind: Tailwind CSS components optimized for React Native with react-native-css-interop
• 🎭 Themed: Native styling with Gluestack's design token system - perfect for branded apps
• 🔧 Unstyled: Headless components for maximum customization in React Native projects

📋 React Native-Optimized Intelligence

• TypeScript-First: Complete TypeScript definitions for React Native component props
• Platform Detection: Smart handling of Platform.OS checks and platform-specific code
• Expo Examples: Real-world usage patterns for Expo Router, EAS Build, and Expo dev workflows
• Performance Patterns: React Native performance best practices baked into component examples

🔄 Cross-Platform Excellence

• Universal Components: Write once, run on iOS, Android, and Web
• Responsive Design: Built-in support for different screen sizes and orientations
• Native Feel: Components follow platform-specific design guidelines automatically
• Web Compatibility: Seamless React Native Web integration for responsive web apps

⚡ Development Acceleration

• GitHub Mode: Access the latest React Native components directly from the repository
• Local Development: Work with local Gluestack UI installations for rapid iteration
• AI-Powered: Generate React Native screens, components, and navigation flows with AI assistance
• Testing Ready: Components come with accessibility labels and test IDs for React Native testing

Quick Start

Prerequisites

• Node.js 18+
• React Native Development Environment:
  • React Native CLI or Expo CLI
  • iOS Simulator (Mac) and/or Android Emulator
  • Metro bundler for React Native
• Component Source (choose one):
  • A local Gluestack UI installation or clone, OR
  • A GitHub Personal Access Token for fetching the latest React Native components

Installation Options

Option 1: From npm (when published)

npm install -g gluestack-ui-mcp-server

Option 2: Local Development Setup

# Clone this repository
git clone https://github.com/gluestack/gluestack-ui-mcp-server
cd gluestack-ui-mcp-server

# Install dependencies
npm install

# Build the project
npm run build

# Set your Gluestack UI path
export GLUESTACK_PATH="/path/to/your/gluestack-ui"

# Test the server
npm test

Usage with Claude Desktop

For Published Package

Add to your Claude Desktop configuration file (~/.config/claude/config.json):

{
  "mcpServers": {
    "gluestack-ui": {
      "command": "npx",
      "args": ["gluestack-ui-mcp-server"],
      "env": {
        "GLUESTACK_PATH": "/path/to/your/gluestack-ui"
      }
    }
  }
}

Or for GitHub mode:

{
  "mcpServers": {
    "gluestack-ui": {
      "command": "npx", 
      "args": ["gluestack-ui-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

For Local Development

Add to your Claude Desktop configuration file (~/.config/claude/config.json):

{
  "mcpServers": {
    "gluestack-ui": {
      "command": "node",
      "args": ["/path/to/gluestack-ui-mcp-server/build/index.js"],
      "env": {
        "GLUESTACK_PATH": "/path/to/your/gluestack-ui"
      }
    }
  }
}

Or for GitHub mode:

{
  "mcpServers": {
    "gluestack-ui": {
      "command": "node",
      "args": ["/path/to/gluestack-ui-mcp-server/build/index.js"], 
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

Available Tools

🔍 Component Discovery & Navigation

list_components

Get a full inventory of all 126+ available Gluestack UI components, including which variants are available for each.

list_component_variants

Compare and choose the perfect variant by getting detailed information and features for a specific component's NativeWind, Themed, and Unstyled versions.

get_directory_structure

Navigate the entire gluestack-ui monorepo from your AI assistant with a powerful directory browsing tool.

📄 Code, Demos & Metadata

get_component

Retrieve the complete, unmodified source code for any component variant, providing perfect context for code generation.

get_component_demo

Access battle-tested usage examples directly from Storybook to understand how components are meant to be used in practice.

get_component_metadata

Go beyond the code to understand its API. This tool extracts TypeScript props, dependencies from import statements, and documentation from comments.

Configuration Options

Environment Variables

• GLUESTACK_PATH: Path to local Gluestack UI installation.
• GITHUB_TOKEN: GitHub Personal Access Token for API access.
• LOG_LEVEL: Logging level (debug, info, warn, error).

Command Line Arguments

# Local mode
gluestack-mcp --gluestack-path /path/to/gluestack-ui --log-level debug

# GitHub mode 
gluestack-mcp --github-token ghp_xxxxxxxxxxxx --log-level debug

GitHub Mode (Fetch Latest Components)

Instead of requiring a local Gluestack UI installation, you can use GitHub mode to fetch the latest components directly from the official repository.

Setting up GitHub Mode

Step 1: Get a GitHub Personal Access Token

1. Go to GitHub Settings → Developer settings → Personal access tokens
2. Generate a new token (classic) with public_repo scope
3. Copy the token (starts with ghp_)

Step 2: Configure Your MCP Client

For Claude Desktop:

{
  "mcpServers": {
    "gluestack-ui": {
      "command": "npx",
      "args": ["gluestack-ui-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

For Command Line:

export GITHUB_TOKEN="ghp_your_token_here"
gluestack-mcp

Benefits of GitHub Mode

• 🚀 Always Up-to-Date: Access the latest components directly from the main branch
• 📦 No Local Setup: No need to clone or maintain a local Gluestack UI repository
• 🔄 Automatic Updates: Components are fetched fresh from GitHub on each request
• 📊 Rate Limit Friendly: Authenticated requests get higher GitHub API limits (5000/hour vs 60/hour)

Supported Components

The server provides access to 126+ Gluestack UI components including:

Layout: Box, Center, HStack, VStack, Grid, Divider Forms: Input, Textarea, Button, Checkbox, Radio, Select, Slider, Switch
Feedback: Alert, Toast, Progress, Spinner, Skeleton Overlay: Modal, AlertDialog, Popover, Tooltip, ActionSheet Data Display: Avatar, Badge, Card, Image, Table Navigation: Tabs, Menu, Link Media: Image, ImageViewer Utilities: Portal, Pressable, SafeAreaView

Testing

The server includes comprehensive tests for both local and GitHub modes:

# Run basic tests
npm test

# Test local mode (requires GLUESTACK_PATH)
npm run test:local

# Test GitHub mode (requires GITHUB_TOKEN)
npm run test:github

# Test both modes
npm run test:both

# Test component discovery
npm run test:components

# Run comprehensive test suite
npm run test:comprehensive

Test Environment Setup

For Local Mode Testing:

export GLUESTACK_PATH=/path/to/gluestack-ui
npm run test:local

For GitHub Mode Testing:

export GITHUB_TOKEN=ghp_your_token_here
npm run test:github

Requirements

• Node.js 18+
• Either:
  • Local Gluestack UI installation/clone (for local mode), OR
  • GitHub Personal Access Token (for GitHub mode)
• MCP-compatible AI client (Claude Desktop, Continue.dev, etc.)

Contributing

We welcome contributions! Please see our for details.

Gluestack UI MCP Server Implementation Summary

🎉 Implementation Complete

The Gluestack UI MCP Server has been successfully implemented with all planned features and capabilities.

✅ Completed Features

1. Project Foundation

• ✅ Complete TypeScript project setup with proper configuration
• ✅ NPM package configuration with all necessary dependencies
• ✅ Build system with TypeScript compilation
• ✅ Executable binary setup with proper shebang

2. Core MCP Server Infrastructure

• ✅ MCP Protocol server implementation using @modelcontextprotocol/sdk
• ✅ STDIO transport for communication with AI clients
• ✅ Request/response handlers for tool calls
• ✅ Comprehensive error handling and logging
• ✅ Server capabilities registration

3. CLI & Configuration

• ✅ Command-line argument parsing (--gluestack-path, --log-level, --help)
• ✅ Environment variable support (GLUESTACK_PATH, LOG_LEVEL)
• ✅ Winston-based logging system with configurable levels
• ✅ Help system with usage examples

4. Component Discovery System

• ✅ Intelligent component detection across multiple variants
• ✅ Support for NativeWind, Themed, and Unstyled component variants
• ✅ Automatic detection of component features (demos, stories, docs)
• ✅ Metadata extraction from package.json and source files
• ✅ Component relationship analysis and dependency tracking

5. MCP Tools Implementation

• ✅ list_components - Lists all 70+ available components
• ✅ get_component - Retrieves component source code
• ✅ get_component_demo - Gets component examples and stories
• ✅ get_component_metadata - Extracts props, dependencies, examples
• ✅ list_component_variants - Shows all variants for a component

6. TypeScript Integration

• ✅ Advanced TypeScript interface parsing for component props
• ✅ Dependency extraction from import statements
• ✅ JSDoc comment extraction for component documentation
• ✅ Type-safe API with comprehensive schemas

7. Multi-Variant Support

• ✅ NativeWind Variant - Modern Tailwind CSS styling (primary)
• ✅ Themed Variant - Gluestack design system tokens
• ✅ Unstyled Variant - Headless components for custom styling
• ✅ Intelligent variant selection with fallbacks

8. Documentation & Testing

• ✅ Comprehensive README with usage examples
• ✅ API documentation for all tools
• ✅ Integration guides for Claude Desktop, Continue.dev, etc.
• ✅ Test scripts and validation
• ✅ MIT License and contribution guidelines

🏗️ Architecture Overview

gluestack-ui-mcp-server/
├── src/
│   ├── index.ts                    # Entry point
│   ├── server/                     # MCP server core
│   │   ├── index.ts               # Server startup logic
│   │   ├── createServer.ts        # Server instance creation
│   │   ├── handler.ts             # Request handlers
│   │   ├── capabilities.ts        # Server capabilities
│   │   └── version.ts             # Version management
│   ├── tools/                      # MCP tool implementations
│   │   └── components/            # Component-related tools
│   │       ├── list-components.ts
│   │       ├── get-component.ts
│   │       ├── get-component-demo.ts
│   │       ├── get-component-metadata.ts
│   │       └── list-component-variants.ts
│   ├── utils/                      # Utilities and helpers
│   │   ├── component-discovery.ts  # Component detection engine
│   │   └── logger.ts              # Logging system
│   └── cli/                       # Command-line interface
│       └── args.ts                # Argument parsing
├── build/                          # Compiled JavaScript
└── README.md                      # Complete documentation

🚀 Key Capabilities

Component Library Support

• 126 Components: Complete Gluestack UI component library coverage
• Cross-Platform: React Native components that work on iOS, Android, Web
• Modern Styling: NativeWind (Tailwind) integration
• Design System: Themed variant with design tokens
• Flexibility: Unstyled variant for complete customization

AI Integration Features

• Rich Context: Provides complete component source code with TypeScript types
• Usage Examples: Real working examples from Storybook demos
• Metadata Extraction: Props interfaces, dependencies, documentation
• Intelligent Search: Component discovery by name or category
• Variant Awareness: Automatically selects best variant for use case

Developer Experience

• Zero Configuration: Works with default paths and settings
• Flexible Setup: Supports custom Gluestack UI installations
• Comprehensive Logging: Detailed debugging and monitoring
• Error Handling: Graceful failures with helpful error messages
• Security Hardened: Package overrides and dependency locking for enhanced security
• Type Safety: Full TypeScript support throughout

🎯 Usage Examples

Basic Component Retrieval

# List all components
echo '{"method": "tools/call", "params": {"name": "list_components"}}' | npx gluestack-ui-mcp-server

# Get Button component source
echo '{"method": "tools/call", "params": {"name": "get_component", "arguments": {"componentName": "Button"}}}' | npx gluestack-ui-mcp-server

Claude Desktop Integration

{
  "mcpServers": {
    "gluestack-ui": {
      "command": "npx",
      "args": ["gluestack-ui-mcp-server"],
      "env": {
        "GLUESTACK_PATH": "/path/to/gluestack-ui"
      }
    }
  }
}

🔧 Technical Decisions

Component Discovery Strategy

• Primary Source: example/storybook-nativewind/src/components/ for rich examples
• Fallback Sources: Core packages for implementation details
• Caching: In-memory component registry for performance
• Multi-Variant: Concurrent discovery across all variant types

TypeScript Parsing

• Regex-Based: Lightweight interface parsing without AST complexity
• Prop Extraction: Automatic detection of component props and types
• Import Analysis: Dependency tracking from import statements
• JSDoc Support: Comment extraction for documentation

Error Handling

• Graceful Degradation: Continue operation even if some components fail
• Detailed Logging: Comprehensive error context for debugging
• User-Friendly Messages: Clear error messages for common issues
• Circuit Breaker: Prevent cascading failures in component discovery

🌟 Benefits for AI Development

Accelerated Development

• Instant Access: Components available to AI assistants immediately
• Best Practices: Examples show proper component usage patterns
• Type Safety: TypeScript interfaces ensure correct prop usage
• Variant Selection: Automatic selection of most appropriate variant

Enhanced Code Quality

• Consistent Styling: Gluestack UI design system principles
• Accessibility: Components built with accessibility best practices
• Cross-Platform: Write once, run on iOS, Android, Web
• Modern Stack: Latest React Native and styling approaches

Productivity Boost

• Reduced Lookup: No need to manually browse documentation
• Complete Context: Source code, examples, and metadata in one request
• Intelligent Discovery: Find components by functionality or name
• Rapid Prototyping: Quickly scaffold UI components

🎊 Ready for Production

The Gluestack UI MCP Server is now complete and ready for:

• AI Assistant Integration (Claude Desktop, Continue.dev, Cursor, etc.)
• NPM Package Publication (gluestack-ui-mcp-server)
• Community Use (Open source with MIT license)
• Enterprise Deployment (Supports custom installations and configurations)

This implementation provides AI assistants with comprehensive access to the Gluestack UI ecosystem, enabling rapid development of high-quality React Native applications with modern styling and cross-platform compatibility.

License

MIT

Built in Melbourne with ❤️ for the Gluestack and AI development communities