---

Install

pipx install aceternity-mcp
aceternity-mcp install

Restart 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 -y

Alternative Install Methods

Docker

docker pull ghcr.io/devinoldenburg/aceternity-mcp
docker run -i ghcr.io/devinoldenburg/aceternity-mcp

npm (wrapper)

npx aceternity-mcp-server

Requires the Python package installed separately (pipx install aceternity-mcp).

pip

pip install aceternity-mcp

From 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.py

Quality

• 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 @aceternity shadcn 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.

Links

• PyPI
• npm
• Docker (ghcr.io)
• GitHub
• Issues
• Model Context Protocol
• Aceternity UI