aceternity-mcp 1.2

An MCP server that exposes a structured registry of Aceternity UI components with rich descriptions, search, recommendations, and installation workflows.

Aceternity MCP

A Model Context Protocol server for Aceternity UI components

Discover, explore, and install 100+ Aceternity UI components directly from your AI assistant. Get intelligent recommendations, detailed metadata, and one-command installations.

---

What is Aceternity MCP?

Aceternity MCP is a Model Context Protocol server that brings the entire Aceternity UI component library to your AI assistant. Instead of just knowing component names, your AI gets rich metadata including:

• Detailed descriptions (60+ words per component)
• Visual characteristics and behavior patterns
• Use case recommendations and compatibility info
• Installation commands and dependencies
• Scoring metrics for animation, customization, performance impact

This helps your AI make informed decisions about which components fit your design needs.

Features

• Complete Registry: Access to 100+ Aceternity UI components with full metadata
• Intelligent Search: Filter by category, visual intensity, animation level, use case
• Smart Recommendations: Get component suggestions based on your project type
• Combination Planning: Recommend complementary components (navbar + hero + CTA)
• One-Command Install: Install components directly through your AI assistant
• Cross-Platform: Works on macOS, Linux, and Windows
• Universal Support: Configures Cursor, Claude Desktop, Claude Code, Cline, Windsurf, OpenCode

Quick Start

Install from PyPI (Recommended)

# Install the package
pip install aceternity-mcp

# Run the interactive setup wizard (recommended for first-time users)
aceternity-mcp install

# Or use the legacy installer
aceternity-mcp-install

# Or configure all tools automatically
aceternity-mcp install --non-interactive

What the installer does:

1. Syncs 100+ components from Aceternity UI (or uses bundled registry)
2. Configures your AI tools automatically
3. Verifies the installation
4. Shows you next steps

CLI Commands

The aceternity-mcp command provides a powerful CLI for managing your installation:

Command	Description
aceternity-mcp install	Run interactive setup wizard
aceternity-mcp update	Check for and install updates
aceternity-mcp repair	Fix common installation issues
aceternity-mcp status	Show installation health and status
aceternity-mcp diagnose	Run diagnostics (JSON output)
aceternity-mcp --version	Show version information
aceternity-mcp --help	Show help message

Examples:

# Check for updates
aceternity-mcp update

# Fix installation issues
aceternity-mcp repair

# Repair only registry
aceternity-mcp repair --registry

# Check installation status
aceternity-mcp status

# Detailed status with client configs
aceternity-mcp status --verbose

# Run diagnostics
aceternity-mcp diagnose

Development Installation

# Clone the repository
git clone https://github.com/devinoldenburg/aceternity-mcp.git
cd aceternity-mcp

# Install in development mode
pip install -e .

# Sync the component registry (optional - registry is included in package)
python scripts/sync_registry.py

# Configure your AI tools
python -m aceternity_mcp.install

Running the MCP Server

To run the MCP server directly (for manual configuration):

# Using the server command
aceternity-mcp-server

# Or using the legacy command
aceternity-mcp-server

Manual Configuration

Add to your AI tool's MCP configuration:

Cursor (~/.cursor/mcp.json):

{
  "mcpServers": {
    "aceternity-ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}

Claude Code (~/.claude/mcp.json):

{
  "mcpServers": {
    "aceternity-ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}

Cline (VS Code extension settings):

{
  "mcpServers": {
    "aceternity-ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}

Windsurf (~/.codeium/windsurf/mcp_config.json):

{
  "mcp_servers": {
    "aceternity_ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}

OpenCode (~/.opencode/mcp.json):

{
  "mcpServers": {
    "aceternity-ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}

Note: When installed via pipx (recommended), the aceternity-mcp command is available in your PATH and no cwd is needed. The registry is bundled with the package.

Available Tools

Once configured, your AI assistant can use these tools:

Tool	Description
list_components	List all available components
list_categories	Show component categories
search_components	Search by name, description, or tags
get_component	Get detailed component information
get_category	Get all components in a category
recommend_components	Get recommendations for your use case
recommend_combination	Suggest complementary components
match_components_to_project	Match components to your project type
install_component	Install a component with dependencies
filter_by_scores	Filter by visual/animation intensity

Example Prompts

Try these with your AI assistant:

"Show me subtle dark background effects with low performance impact"
"Recommend a navbar + hero + CTA combination for a SaaS landing page"
"Find highly customizable card components for testimonials"
"Give me low-motion components suitable for a dashboard"
"Install Spotlight and show me what dependencies are needed"
"What components work well for dark mode dashboards?"
"Show me animated text effects that aren't too distracting"

Architecture

aceternity-mcp/
├── registry/              # Component metadata registry (bundled with package)
│   ├── index.json        # Master index
│   ├── raw/              # Raw data from Aceternity UI
│   ├── components/       # Enriched component metadata
│   └── categories/       # Category definitions
├── scripts/              # Utility scripts
│   ├── sync_registry.py  # Sync from Aceternity UI (optional)
│   └── validate_registry.py
├── src/aceternity_mcp/   # MCP server source
│   ├── server.py         # MCP server implementation
│   ├── install.py        # Universal installer
│   ├── models.py         # Data models
│   ├── registry.py       # Registry loader (finds registry in pipx share/)
│   ├── search.py         # Search functionality
│   └── recommender.py    # Recommendation engine
└── pyproject.toml        # Package configuration (includes registry in shared-data)

When installed via pipx, the registry is automatically available at:

~/.local/pipx/venvs/aceternity-mcp/share/aceternity-mcp/registry/

Development

Validate Registry Quality

# Compile check
python -m compileall src scripts

# Validate registry schema
python scripts/validate_registry.py

Update Component Registry

# Sync latest components from Aceternity UI (optional)
python scripts/sync_registry.py

# With API key (optional)
python scripts/sync_registry.py --api-key "$ACETERNITY_API_KEY"

# Reinstall to bundle updated registry
pipx reinstall aceternity-mcp

Note: The registry is bundled with the package, so running sync_registry.py is only needed if you want to update to the latest components from Aceternity UI.

CLI Development

The CLI provides management commands for end users:

# Test CLI commands
aceternity-mcp --help
aceternity-mcp status
aceternity-mcp diagnose

# Test update check
aceternity-mcp update --non-interactive

# Test repair functionality
aceternity-mcp repair --non-interactive

Supported AI Tools

Tool	Config File	Status
Cursor	~/.cursor/mcp.json	✅ Supported
Claude Desktop	Platform-specific	✅ Supported
Claude Code	~/.claude/mcp.json	✅ Supported
Cline	VS Code extension	✅ Supported
Windsurf	~/.codeium/windsurf/mcp_config.json	✅ Supported
OpenCode	~/.opencode/mcp.json	✅ Supported

Requirements

• Python: 3.10 or higher
• Node.js: Required for registry sync (npx command)
• MCP Client: One of the supported AI tools listed above

Security

• No secrets are committed to the repository
• API keys are optional and used only during sync operations
• Keys are not stored on disk
• The repository stores metadata descriptions, not component source files

Contributing

Contributions are welcome! Please see:

• Contributing Guide
• Code of Conduct
• Security Policy

License

MIT License - see LICENSE for details.

Links

• PyPI Package
• GitHub Repository
• Issue Tracker
• Model Context Protocol