Findings & checks · 0 flagged
Every scanned point with the score it earned and what moved between them.
First recorded scan — no prior version to compare against.
The primary manifest — the file an agent reads to learn what this artifact does.
<div align="center">
Aceternity MCP
Model Context Protocol server for Aceternity UI components
Discover, search, and install 106 Aceternity UI components from your AI assistant. Generate full page layouts, get context-aware recommendations, and install everything with a single command.
</div>
Install
pipx install aceternity-mcp
aceternity-mcp installRestart your AI tool. Done.
What It Does
Your AI assistant gets 11 tools for working with Aceternity UI:
| Tool | What it does |
|---|---|
generate_page_layout | Generate a full page layout with sections, components, and install commands |
search_components | Full-text search across names, descriptions, tags, categories |
recommend_components | Get recommendations for a use case or design goal |
recommend_combination | Get component suggestions for each page section |
match_components_to_project | Match components to a whole project description |
list_components | List all 106 components with optional filters |
list_categories | Show all 17 categories with component counts |
get_component | Get full metadata for a single component |
get_category | Get all components in a category |
install_component | Get install command, dependencies, and setup steps |
filter_by_scores | Filter by visual intensity, animation, performance, etc. |
Page Layout Generator
The standout feature. Ask your AI to generate a complete page layout and it returns:
- Ordered sections with recommended components for each role
- Design tone detection (dark, premium, modern, minimal, etc.)
- Section-specific scoring using 17 role profiles
- De-duplicated components across sections
- Implementation notes for every section
- Batch install command for all components at once
- Performance estimate and dependency summary
7 page types: landing, saas, dashboard, portfolio, ecommerce, blog, documentation
Example prompts:
"Generate a page layout for a dark premium AI SaaS landing page"
"Build me a fintech dashboard layout with analytics"
"Create a portfolio page with 3D effects and scroll animations"
"Design an e-commerce store layout for a clothing brand"Scoring signals per component:
| Signal | Description |
|---|---|
| Section-role category match | 17 role profiles with preferred categories |
| Section-role tag match | Role-specific tag boosting |
| Section score weights | Tuned dimension weights per role |
| Archetype context | Page-level scoring (SaaS, dashboard, portfolio, etc.) |
| Text relevance | User description keyword matching |
| Design tone coherence | Boosts components matching detected tones |
| Dependency reuse | Bonus for shared npm dependencies |
Example Prompts
"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?"
"Search for animated text effects"
"Filter components with visual intensity above 7 and low performance impact"Supported AI Tools
| Tool | Auto-configured |
|---|---|
| Claude Desktop | Yes |
| Claude Code CLI | Yes |
| Cursor | Yes |
| Cline (VS Code) | Yes |
| Windsurf | Yes |
| OpenCode | Yes |
Run aceternity-mcp install and all detected tools are configured automatically.
Manual Configuration
All tools use the same server command:
{
"mcpServers": {
"aceternity-ui": {
"command": "aceternity-mcp-server",
"args": []
}
}
}| Tool | Config file |
|---|---|
| Cursor | ~/.cursor/mcp.json |
| Claude Code | ~/.claude/mcp.json |
| Cline | VS Code extension settings |
| Windsurf | ~/.codeium/windsurf/mcp_config.json (uses mcp_servers / aceternity_ui) |
| OpenCode | ~/.opencode/mcp.json |
CLI Commands
| Command | Description |
|---|---|
aceternity-mcp install | Interactive setup wizard |
aceternity-mcp status | Show installation health |
aceternity-mcp update | Check for and install updates |
aceternity-mcp repair | Fix registry, configs, or permissions |
aceternity-mcp diagnose | Output JSON diagnostics |
aceternity-mcp uninstall | Remove from all AI tools |
aceternity-mcp --version | Show version |
# Repair only the registry
aceternity-mcp repair --registry
# Repair only client configs
aceternity-mcp repair --configs
# Non-interactive update
aceternity-mcp update -yAlternative Install Methods
Docker
docker pull ghcr.io/devinoldenburg/aceternity-mcp
docker run -i ghcr.io/devinoldenburg/aceternity-mcpnpm (wrapper)
npx aceternity-mcp-serverRequires the Python package installed separately (pipx install aceternity-mcp).
pip
pip install aceternity-mcpFrom source
git clone https://github.com/devinoldenburg/aceternity-mcp.git
cd aceternity-mcp
pipx install .Component Registry
106 components across 17 categories:
| Category | Count | Examples |
|---|---|---|
| Backgrounds | 18 | Aurora, Beams, Grid, Spotlight, Vortex |
| Cards | 15 | 3D Card, Card Hover, Expandable Card |
| Text Effects | 13 | Typewriter, Text Generate, Gradient Text |
| Scroll Effects | 11 | Parallax, Scroll Reveal, Tracing Beam |
| Visualization | 9 | Globe, World Map, SVG Mask |
| Hero Sections | 8 | Hero Parallax, Spotlight, Lamp Effect |
| Navigation | 7 | Floating Dock, Navbar Menu |
| Layout | 81 | Bento Grid, Container Scroll, Timeline |
| Forms | 6 | Input, Placeholders, Multi-Step |
| 3D Effects | 5 | 3D Card, 3D Pin, Globe |
Each component includes: detailed description, purpose, behavior, visual characteristics, design tone, difficulty level, dependencies, install command, compatibility flags, and 7 scoring dimensions.
Scoring Dimensions
Every component is rated 1-10 on:
| Dimension | What it measures |
|---|---|
| Visual Intensity | How visually dominant (1 = subtle, 10 = dramatic) |
| Animation Intensity | Amount of motion (1 = static, 10 = heavy animation) |
| Layout Importance | Structural criticality (1 = decorative, 10 = essential) |
| Customization Ease | Flexibility (1 = rigid, 10 = very configurable) |
| Landing Page Fit | Suitability for landing pages |
| Dashboard Fit | Suitability for dashboards |
| Performance Impact | Runtime cost (1 = lightweight, 10 = heavy) |
Development
git clone https://github.com/devinoldenburg/aceternity-mcp.git
cd aceternity-mcp
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
# Run tests
pytest tests/ -v
# Lint + type check
ruff check src/ tests/
mypy src/aceternity_mcp/ tests/
# Validate registry
python scripts/validate_registry.pyQuality
- 172 tests, 9 archetypes, 17 section role profiles, 7 page templates
- ruff lint + format, mypy strict, bandit security scan
- CI: quality gates on every push, auto-publish on release
Security
- Metadata only: No Aceternity source code, documentation, or images in this repository
- No secrets: No API keys or credentials
- Isolated: pipx provides sandboxed virtual environments
- Install commands: Point to Aceternity's official
@aceternityshadcn registry
Troubleshooting
Command not found -- Run pipx ensurepath and restart your terminal.
Registry not found -- Run aceternity-mcp repair or pipx reinstall aceternity-mcp.
MCP server not connecting -- Run aceternity-mcp diagnose and check the output. Repair configs with aceternity-mcp repair --configs.
Update issues -- Run pipx upgrade aceternity-mcp or pipx reinstall aceternity-mcp.
License
MIT -- see LICENSE.