What you can do
The shads.app MCP server lets a coding assistant work with themes directly instead of scraping the builder or pasting CSS into a prompt. Once connected, ask your assistant:
- Install the Claret theme from shads in this repo.
- List the shads design systems and catalog themes.
- Validate this Theme v1 document with shads.
- Install a theme saved in my library.
- Save or update a theme in shads from this project (Pro).
- Generate and save a calm, high-contrast theme for a finance dashboard (Pro).
Without a key, agents can browse the catalog and install the three Free-tagged themes. A Free account API key installs saved themes and reads your library. Pro adds the save_theme, update_theme, and generate_theme write tools.
Connect in a minute
The server is remote: nothing to install, no Node, no local process. Its address is https://mcp.shads.app.
Pick your client for a one-click or one-command setup:
| Client | Fastest setup |
|---|---|
| Cursor | One-click install |
| VS Code | One-click install (GitHub Copilot agent mode) |
| Claude Code | One command |
| Codex | One command (CLI and IDE share config) |
| Claude Desktop / claude.ai | Add a custom connector |
| Windsurf | Edit mcp_config.json |
| Zed | Add a remote server in Settings |
| Gemini CLI | Edit settings.json |
Any other client: run npx add-mcp https://mcp.shads.app, or point it at the server URL above.
Then check that it works.
Check that it works
Ask your assistant:
Use the shads MCP server and run connection_status.
It returns the server version, whether your API key was accepted, your plan, and which tools are available. If it does not answer, see troubleshooting.
Free and Pro
| Capability | No key | Free account key | Pro account key |
|---|---|---|---|
| Browse design systems and the complete theme catalog | Yes | Yes | Yes |
| Install the three Free-tagged themes | Yes | Yes | Yes |
| Install saved themes and read your library | — | Yes | Yes |
| Save and update themes with MCP | — | — | Yes |
| Generate themes with MCP | — | — | Yes |
Create the single API key for your account in Account settings → API keys, then follow authentication to add it to your client. Regenerating the key disconnects tools using the previous one. A missing or invalid key never breaks the connection: public tools remain available and connection_status explains the key status.
A saved theme uses one of your three Free lifetime activations on its first install. After it is activated, it installs any number of times; deleting it does not refund the activation. Pro has unlimited activations.
Use it in a project
Recipes cover installing a Free catalog theme, installing a theme saved in the builder, generating with Pro tools, and validating a Theme v1 document.
Tools
The full list, with example arguments, is in the tools reference. You rarely call tools by hand: describe what you want and the assistant picks them.
Get help
- Troubleshooting: "I do not see any shads tools", "only public tools", rate limits.
- Each client page ends with fixes specific to that client.
FAQ
Do I need an account?
No. Browse the catalog and install the three Free-tagged themes without an account. A Free account API key installs saved themes and reads your library; Pro adds MCP write tools.
How many API keys can I create?
One API key is available per account. Regenerating it immediately disconnects every tool still using the old key.
Which clients are supported?
Any client that supports remote MCP over Streamable HTTP. Cursor, VS Code, Claude Code, Codex, Claude, Windsurf, Zed, and Gemini CLI have dedicated guides above. For anything else, run npx add-mcp https://mcp.shads.app or paste the server URL into the client's MCP settings.
I used the @shadsapp/mcp npm package. What changed?
That package is deprecated. Remove the npx @shadsapp/mcp entry from your client config and use the remote server above instead.