README.md•8.45 kB
# ReactBits MCP Server
A Model Context Protocol (MCP) server that provides AI assistants with access to [ReactBits.dev](https://reactbits.dev) components - a collection of 135+ animated React components for creative developers.
> ⚠️ **Important Note**: Some ReactBits components (buttons, forms, loaders) currently have incomplete implementations. See [Component Quality Status](#component-quality-status) below.
## Features
- 🎨 **Component Discovery**: Browse and search through all ReactBits components
- 🔍 **Smart Search**: Find components by name, category, or description
- 💅 **Style Options**: Access both CSS and Tailwind versions of components
- 📁 **Category Navigation**: Filter components by categories (animations, backgrounds, buttons, etc.)
- 🚀 **Fast Performance**: Built-in caching for optimal response times
- 📝 **Demo Generation**: Get usage examples and demo code for any component
## Installation
```bash
# Install globally
npm install -g reactbits-dev-mcp-server
# Or run directly with npx (no installation required)
npx reactbits-dev-mcp-server
# Or install as a dependency
npm install reactbits-dev-mcp-server
```
### From Source
```bash
# Clone the repository
git clone https://github.com/yourusername/reactbits-mcp-server
cd reactbits-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Run the server
npm start
```
## Configuration
### Claude Desktop
Add to your Claude Desktop configuration:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"reactbits": {
"command": "npx",
"args": ["reactbits-dev-mcp-server"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}
```
### VS Code (with Continue extension)
Add to your VS Code settings:
```json
{
"continue.server": {
"mcpServers": {
"reactbits": {
"command": "npx",
"args": ["reactbits-dev-mcp-server"]
}
}
}
}
```
### Cursor
Add to your Cursor settings or `.cursorrules`:
```json
{
"mcpServers": {
"reactbits": {
"command": "npx",
"args": ["reactbits-dev-mcp-server"],
"env": {
"GITHUB_TOKEN": "your_github_token_here"
}
}
}
}
```
## Quick Start
```bash
# Clone and install
git clone https://github.com/yourusername/reactbits-mcp-server
cd reactbits-mcp-server
npm install
# Build
npm run build
# Test locally
node test-list-components.js
```
## Available Tools
### `list_components`
List all available ReactBits components with optional filtering.
**Parameters:**
- `category` (optional): Filter by category (e.g., "animations", "backgrounds", "buttons")
- `style` (optional): Filter by styling method ("css", "tailwind", "default")
- `limit` (optional): Maximum number of components to return
**Example:**
```
"List all animation components with Tailwind support"
```
### `get_component`
Get the source code for a specific ReactBits component.
**Parameters:**
- `name` (required): Name of the component (e.g., "splash-cursor", "pixel-card")
- `style` (optional): Preferred styling method ("css", "tailwind", "default")
**Example:**
```
"Show me the source code for the splash cursor component"
```
### `search_components`
Search for ReactBits components by name or description.
**Parameters:**
- `query` (required): Search query
- `category` (optional): Filter by category
- `limit` (optional): Maximum number of results
**Example:**
```
"Find all components related to cards"
```
### `get_component_demo`
Get usage example and demo code for a ReactBits component.
**Parameters:**
- `name` (required): Name of the component
**Example:**
```
"Show me how to use the glow button component"
```
### `list_categories`
List all available component categories.
**Example:**
```
"What categories of components are available?"
```
## Usage Examples
### With AI Assistants
Once configured, you can ask your AI assistant questions like:
- "Show me all the background animation components from ReactBits"
- "I need a glowing button component - what's available?"
- "How do I implement the particle background effect?"
- "Find all text animation components that support Tailwind"
- "Show me the code for the glass morphism card component"
### Component Categories
ReactBits components are organized into the following categories:
- **Animations**: Dynamic cursor effects and interactive animations
- **Backgrounds**: Animated and static background patterns
- **Buttons**: Interactive button components with various effects
- **Cards**: Card components with hover effects and animations
- **Text Animations**: Animated text effects and reveals
- **Components**: General UI components and layouts
- **Navigation**: Navigation menus and interfaces
## Development
### Project Structure
```
reactbits-mcp-server/
├── src/
│ ├── index.ts # Main server entry point
│ ├── services/
│ │ └── ReactBitsService.ts # Component fetching logic
│ ├── types/
│ │ └── index.ts # TypeScript type definitions
│ └── utils/
│ └── CacheManager.ts # Caching utility
├── dist/ # Compiled output
├── package.json
├── tsconfig.json
└── README.md
```
### Building
```bash
# Install dependencies
npm install
# Build the project
npm run build
# Run in development mode
npm run dev
```
### Testing
```bash
# Run the MCP inspector for debugging
npx @modelcontextprotocol/inspector
```
## GitHub API Token (Optional but Recommended)
The server can work without a GitHub token but will be limited to 60 requests per hour. With a token, you get up to 5,000 requests per hour.
### Setting up a GitHub Token
1. Create a GitHub personal access token at https://github.com/settings/tokens
- Click "Generate new token (classic)"
- No special scopes needed (public repository access only)
- Copy the generated token
2. Set it as an environment variable:
```bash
# Option 1: Export in your shell
export GITHUB_TOKEN=your_token_here
# Option 2: Create a .env file (copy from .env.example)
cp .env.example .env
# Edit .env and add your token
# Option 3: Pass when running the server
GITHUB_TOKEN=your_token_here npx reactbits-dev-mcp-server
```
**⚠️ Security Note**: Never commit your GitHub token to version control. Always use environment variables.
## Component Quality Status
Based on comprehensive testing, here's the current quality status of ReactBits components:
### ✅ Excellent Quality (9.0-10/10)
- **Backgrounds** (9.8/10): Aurora, Beams, Particles, etc. - Production-ready WebGL effects
- **Animations** (9.5/10): BlobCursor, SplashCursor, Magnet, etc. - Professional animations
- **Text Animations** (9.0/10): BlurText, CountUp, CircularText, etc. - Complete Framer Motion
### ⚠️ Incomplete Components (2.0/10)
- **Buttons**: All 8 button components return placeholder code
- **Forms**: All 3 form components are incomplete
- **Loaders**: All 9 loader components are incomplete
### 📦 Dependencies
The MCP server now includes dependency information for each component:
- `framer-motion`: Text animations and interactive components
- `gsap`: Cursor animations and advanced interactions
- `three.js` / `@react-three/fiber`: 3D backgrounds and effects
- `ogl`: WebGL rendering (Aurora component)
## Contributing
Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.
1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add 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
- [ReactBits.dev](https://reactbits.dev) for the amazing component collection
- [Anthropic](https://anthropic.com) for the Model Context Protocol specification
- The MCP community for inspiration and examples
## Support
- 🐛 [Report Issues](https://github.com/ceorkm/reactbits-mcp-server/issues)
- 💬 [Discussions](https://github.com/ceorkm/reactbits-mcp-server/discussions)