@shoppexio/mcp-theme-server

Model Context Protocol server for Shoppex theme operations. 22 tools including the flagship theme_ai_apply — natural-language theme editing powered by the Shoppex Theme Builder Agent.

Install

The fastest way is the one-shot installer:

npx @shoppexio/mcp-shoppex install --api-key shx_your_dev_api_key

That installs both commerce and theme MCPs. Or install themes standalone:

npm install -g @shoppexio/mcp-theme-server

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "shoppex-themes": {
      "command": "npx",
      "args": ["-y", "@shoppexio/mcp-theme-server"],
      "env": {
        "SHOPPEX_API_KEY": "shx_your_dev_api_key"
      }
    }
  }
}

Restart Claude Desktop.

Tools (22)

Discovery

• theme_list — list all themes for the shop
• theme_inspect — editable areas, sections, settings, tokens
• theme_diff — draft vs. published
• theme_read_file — read one source file
• theme_search_files — grep across theme files

Authoring

• theme_ai_apply — natural-language theme editing. The Theme Builder Agent plans, edits files, verifies the build, and hands back a draft. Examples: "add a testimonials section above the footer", "switch the accent color to purple", "fix the homepage hero to center-align on mobile".
• theme_apply — apply explicit file changes (for precise edits)
• theme_accept — accept a pending draft from an agent run
• theme_create — scaffold from a base theme
• theme_create_section — add a section
• theme_create_page — add a page/route
• theme_update_config — extend theme.config.ts

Preview & Publish

• theme_preview — start a live preview session
• theme_stop_preview — stop a preview
• theme_publish — deploy the accepted draft
• theme_publish_status — check publish job status
• theme_validate — validation-only build + optional typecheck

Settings & History

• theme_settings_get / _settings_update — builder settings
• theme_backups — list backups
• theme_rollback — roll back to a backup
• theme_latest_run — last agent-run metadata

Example prompts

• "List my themes and inspect the active one." — theme_list → theme_inspect
• "Add a testimonials section above the footer." — theme_ai_apply → theme_preview → (user approves) → theme_accept → theme_publish
• "Make the hero background a subtle purple gradient." — single theme_ai_apply call
• "Create a new theme from Pulse and set it as active." — theme_create
• "Roll back the active theme to yesterday's backup." — theme_backups → theme_rollback

The theme_ai_apply flow

The flagship tool. User sends a natural-language edit request; the Theme Builder Agent:

1. Plans the change (which files, which sections)
2. Edits the files with Claude Opus structured outputs
3. Runs a verification build (+ optional typecheck)
4. Returns a draft with run_id + file summary

Chain it with theme_preview to get a live URL, then theme_accept + theme_publish to ship.

Claude Desktop's default flow after a theme_ai_apply call looks like:

assistant: Done. Draft run_id=run_3a8. I added a TestimonialsSection above
the footer with 3 placeholder quotes. Build: green.

Preview: https://preview-p7q.shoppex.dev

Say "publish" to ship.

user: publish

assistant: [theme_accept]
[theme_publish]
Live. ✅

Environment Variables

| Variable | Required | Default | |----------|----------|---------| | SHOPPEX_API_KEY | yes | — | | SHOPPEX_API_URL | no | https://api.shoppex.io |

Create an API key at dashboard.shoppex.io/developer/api.

Required Scopes

• themes.read
• themes.write

Companion

Pair with @shoppexio/mcp-commerce-server for products, orders, customers, coupons, payment links, and more.

Agent Templates

A dedicated Theme Agent template (paste-ready for Claude Desktop Projects): docs/agents/theme.md

Docs

• AI Workflows
• Build & Customize with AI
• Developer API

License

Proprietary. © Shoppex.