shadcn/ui components in OpenCode
Add a shadcnio entry to opencode.json and OpenCode can find shadcn components, blocks and icons and install them in your repo. It needs a shadcn.io Pro plan, whatever model you run.
- Kind
- Terminal agent
- Goes in
opencode.json- Connects
- Over HTTP
- Team config
- Yes
Add it to opencode.json
OpenCode keeps MCP servers under an mcp key, and a hosted one is "type": "remote". Signed in with Pro, the entry beside these steps is filled in with your own URL.
Copy the entry
It's your MCP URL, token at the end, under
mcp.shadcnio. No token yet? Create one on your account page and reload this page.Merge it into opencode.json
Use
~/.config/opencode/opencode.jsonfor every project, oropencode.jsonat the repo's root for this one. Keep your other settings, and putshadcniobeside any servers already undermcp.Restart OpenCode
OpenCode connects to its enabled servers as it starts. Quit with
/exit, runopencodein the project again, andopencode mcp listshould showshadcnioconnected.Ask from the Build agent
Begin with
use shadcnio…so the model goes to the registry. Plan can search but can't edit files, so pressTabto get back to Build before you install.
How it reads, with YOUR_TOKEN where your token goes:
{ "mcp": { "shadcnio": { "enabled": true, "type": "remote", "url": "https://www.shadcn.io/api/mcp?token=YOUR_TOKEN" } } }
OpenCode merges every config it finds, so a project's shadcnio entry wins over your global one, and opencode debug config prints the result. Regenerating your token on your account turns off the old URL.
| File | Applies to | Good to know |
|---|---|---|
~/.config/opencode/opencode.json | You, in every project | Your URL stays out of every repo |
opencode.json at the repo's root | Everyone who works in the repo | Found from the current folder up to the Git root; commit it with {env:SHADCNIO_TOKEN} |
The file in OPENCODE_CONFIG | Any shell that sets the variable | Loads after the global file and before the project's |
opencode.jsonc | Either place | The same keys, with comments allowed |
One opencode.json for the team
Commit opencode.json at the root with the token in its URL written as {env:SHADCNIO_TOKEN}. OpenCode fills that in from each person's environment when it starts, so no token goes into git. Each teammate exports their own; when the variable is missing, the token comes through empty and the server answers 401. With a Team or Organization plan, each person's own token comes with Pro.
{ "mcp": { "shadcnio": { "enabled": true, "type": "remote", "url": "https://www.shadcn.io/api/mcp?token={env:SHADCNIO_TOKEN}" } } }
Each teammate sets SHADCNIO_TOKEN to their own token (from their MCP URL), so no token is committed.
Check OpenCode connected
opencode mcp list prints each server with its status: a check and connected when it works, the error when it doesn't. In the TUI, /status shows the same list.
- Quit OpenCode and run
opencodein the project again, so it reads the new entry. - In the same folder, run
opencode mcp list:shadcnioshould be marked connected. - Or type
/statusin the TUI and findshadcniounder MCP Servers, marked Connected. - Ask the prompt below. OpenCode calls
whoamiand answers with your account and how many calls you have left this minute.
Three tasks in OpenCode
A toast in a SolidStart app, a landing page planned before it's built, an editor for env vars: the prompt, the tools OpenCode calls, and what changes in the repo. Switch the MCP off to compare.
- shadcn.io MCP connected · 22 tools
Agent step: Read package.jsonReturns: SolidStart, @ark-ui/solid, bunMCP call: search_components({ query: "toast notification", framework: "solid" })Returns: toast, the closest matchMCP call: get_install_plan({ name: "toast", framework: "solid", packageManager: "bun" })Returns: Each file with its path, and the packages to addAgent step: Wrote the files and ran bun addReturns: src/components/ui/toast.tsx, a Toaster in app.tsx
In your project
Toast
- A toaster that stacks and dismisses them for you
- Fired from the invite action once it succeeds
1 prompt → 2 MCP calls
Prompts to paste into OpenCode
Paste one at OpenCode's prompt. Each names the server first, so the model reaches for the registry instead of writing UI from memory.
Worth knowing in OpenCode
Slash commands, agents, permissions and rules files: the parts of OpenCode that change how it uses the registry.
Seven prompts as slash commands
Type
/and the server's prompts are listed as/shadcnio:add,/shadcnio:block,/shadcnio:pageand four more, marked:mcp. The words after the command fill in its arguments, and OpenCode sends the task with the calls that do it./shadcnio:icons home, settings, log out
A line in AGENTS.md
OpenCode reads
AGENTS.mdin the project, orCLAUDE.mdwhen there's none, and/initwrites one for you. One line there and you can dropuse shadcniofrom your prompts.Build UI with the shadcnio MCP: search it for a component or block first, then run the install command it returns.
Plan with the registry, then build
Press
Tabfor Plan. It can't edit your files, but it can call the shadcnio tools, so it can pick a page's blocks withplan_pageand write the plan down.Tabback to Build to install them.Ask before shell commands
By default OpenCode runs tools and shell commands without asking,
npx shadcn addincluded. To check each command first, setbashto ask and allow the installs you trust; the last matching rule wins, so*goes first.{ "permission": { "bash": { "*": "ask", "npx shadcn@latest add *": "allow" } } }
Attach a brand's DESIGN.md with @
Type
@and a brand's slug, likeposthog: beside your files, OpenCode lists the server's DESIGN.md for it. Pick it and the whole file goes into your message as context.One-off runs with opencode run
opencode runtakes one prompt and exits, which suits scripts. Each run starts its MCP servers again; withopencode servealready running,--attachpoints the run at it and skips that wait.$ opencode run "use shadcnio to add a skeleton to the deploys table while it loads"
If OpenCode can't reach shadcnio
What opencode mcp list or a toast in the TUI tells you, and the fix. The troubleshooting guide covers every client.
shadcnioisn't inopencode mcp listat all.- OpenCode only reads servers under a top-level
mcpkey, so anmcpServersblock copied from another editor doesn't load. Check you edited the file OpenCode uses:opencode debug configprints what it resolved. - OpenCode says
shadcnioneeds authentication. - shadcnio doesn't use OAuth: the token rides in the URL. A missing or old one gets a 401, which OpenCode reads as a sign-in request, so copy the entry again instead of running
opencode mcp auth. With"oauth": falsein the entry, a bad token shows as failed instead. - The shared
opencode.jsonfails for one teammate. {env:SHADCNIO_TOKEN}turns into an empty string when the variable isn't set, so the request carries no token. Export it in your shell profile, open a new terminal and startopencodeagain.- Calls to shadcnio fail with a 403.
- OpenCode reached the server and the token is right, but the account has no active Pro plan. Renew it and restart: nothing in the entry changes.
opencode mcp listshowsshadcnioas disabled.- The entry has
"enabled": false. Set it totrue, or remove the key, then quit and start OpenCode again. - OpenCode writes UI from memory instead of calling the tools.
- Start the prompt with
use shadcnio, or add the line from the tips toAGENTS.md. If you're in Plan, it can look things up but won't install: pressTabfor Build.
Get the MCP for OpenCode with Pro
The MCP comes with every Pro plan, with every block and premium template, for you or your whole team. Monthly, yearly or lifetime.
4.9/5 out of 5 · 150+ reviewsfrom 150+ founders and developers.
- Secure checkout via Stripe
- Code lives in your repo
- Keep what you've shipped if you cancel
- License terms
Frequently asked questions
The shadcn MCP in OpenCode: setup, limits, and the rest.
The global file at ~/.config/opencode/opencode.json gives you shadcnio in every project with your own URL, kept out of every repo. The project's opencode.json, committed with the token read from SHADCNIO_TOKEN, gives it to everyone on the repo. You can have both: OpenCode merges them, and the project's values win where they differ.
Yes. Run opencode mcp add, choose this project or global, name the server shadcnio, pick Remote, paste your MCP URL from this page and answer No when it asks about OAuth. It writes the same entry into opencode.json for you.
Run opencode mcp list in the project folder: shadcnio should say connected. Inside the TUI, /status lists it under MCP Servers. Then ask OpenCode to use shadcnio and tell you who you're connected as; it calls whoami and answers with your account and the calls left this minute.
No. OpenCode reads its config when it starts, so quit with /exit and run opencode again after every change to the shadcnio entry.
Plan is OpenCode's read-only agent: it can't edit files, apart from its own plan notes. It can still call the shadcnio tools, which only read the registry, so it can pick components or a page's blocks. Press Tab to switch to Build and ask it to carry out the plan.
They're the server's seven prompts, which OpenCode lists as commands: add, block, form, setup, page, icons and design, each after shadcnio:. Type one with its argument, like /shadcnio:design linear, and OpenCode sends the task written out with the calls that do it.
Not by default. OpenCode allows tools and shell commands unless your permission config says otherwise. The shadcnio tools only read the registry, so that's fine for them; if you want to see each install command first, set bash to ask in opencode.json.
In React, the server returns one shadcn command and OpenCode runs it. In Vue, Svelte and Solid it answers get_install_plan with every file, its path and the packages to add, and OpenCode writes the files and installs the packages with your package manager.
It chooses tools from your prompt, and a vague one looks answerable from memory. Start with use shadcnio, name the component or the page, and add a line to AGENTS.md telling it to search the shadcnio MCP before writing UI.
Any model you've connected with /connect, as long as it can call tools. The server lives in your OpenCode config, not with a provider, so switching models with /models keeps it. Your provider bills the model, and shadcn.io Pro covers the registry on its own.
Each tool's definition goes along with your requests, and OpenCode's docs warn that MCP servers add up in the context window. In a repo that never needs UI work, set enabled to false on the shadcnio entry in that project's opencode.json, and turn it back on when you do.
Commit opencode.json at the repo's root with the token at the end of the URL written as {env:SHADCNIO_TOKEN}. OpenCode fills it in from each person's environment at startup, so no token reaches git. Every teammate exports their own, and a Team or Organization plan gives each member Pro.
Your global file sits in your home folder like any CLI credential, outside every repo. In a file you commit, use {env:SHADCNIO_TOKEN} instead of the token itself. If a token leaks, regenerate it on your account page and the old URL stops working.
OpenCode merges every config it finds rather than picking one. The project's opencode.json comes after the global file, so for the same shadcnio entry the project's url is the one used, and a teammate's global copy is simply overridden.
shadcnio doesn't use OAuth: your token travels in the URL. When the token is missing or old, the server answers 401 and OpenCode takes that as a request to sign in. Copy the entry again, or export SHADCNIO_TOKEN for the shared config, then restart. Adding oauth set to false makes a bad token show as a plain failure.
A 401 means the token is missing or no longer valid, as after you regenerate it. A 403 means OpenCode got through with a good token, but Pro has lapsed on that account. A 429 means one token made more than 600 calls in a minute; wait for the time Retry-After gives.
Set enabled to false on the shadcnio entry and restart OpenCode: it stays in the file and shows as disabled in opencode mcp list. Set it back to true to use it again, or delete the entry from mcp to remove it for good.
Using another agent too?
The same URL works in every MCP client: use it beside OpenCode, in your editor, your terminal or your chat app.
4.9 out of 5 from 150+ developers
Put the registry in OpenCode
One remote entry in opencode.json, and every component, 6,231 blocks and 294k icons are a prompt away in your terminal, on any Pro plan.
Get Pro