MCP 服务器

aceternity-mcp

MCP server for Aceternity UI components, enabling AI assistants to discover, search, install, and generate page layouts with 106 components.

README

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