Shadcn MCP does not connect in Cursor: diagnosis in five steps

Short answer: the MCP server is a child process of the editor. If the editor cannot find npx, cannot read the configuration file, or has no valid project, the connection never starts. Run the command by hand: it is the quickest diagnosis.

How an MCP server talks

A local MCP server opens no port and exposes no HTTP endpoint: it talks over stdin and stdout in JSON-RPC. The editor starts the command as a child process, writes an initialise request and waits for the answer. If the process never starts, writes nothing, or writes something that is not JSON-RPC, the MCP panel stays empty. There is no network timeout to inspect, because there is no network.

The delicate part is that the editor does not use a shell. It launches the command directly, with the environment it inherited when it opened, not the one in your terminal. On Windows npx is a .cmd shim rather than an executable, so a direct call fails with ENOENT; on macOS an editor started from the Dock never reads the PATH from .zshrc. Two faces of the same problem: the child process does not see what you see.

Five steps, in order

1. Open a terminal in the project root and run the server command: if it fails there, it will fail in the editor too.
2. Check that you are in the folder that holds components.json.
3. Open the editor's MCP configuration file and check the JSON syntax.
4. On Windows, invoke cmd /c npx instead of npx.
5. Restart the whole editor, not just the window.

A typical configuration

{
  "mcpServers": {
    "shadcn": {
      "command": "cmd /c npx",
      "args": ["shadcn@latest", "mcp"]
    }
  }
}

On macOS and Linux the command field is npx and args stays the same. The file path depends on the editor: some read a global configuration, others one inside the project folder. When both exist, the project one wins.

The diagnostic step

# run the exact command from the editor config, in the project root
npx shadcn@latest mcp

# the server must stay open and print nothing on stdout:
# that stream carries JSON-RPC only, diagnostics go to stderr

If the command stays open with no output, the server works and the fault is in the editor configuration. If it prints an error and exits, the cause is on screen: copy it. If it starts and closes at once, the project is missing. The detail that misleads is that a healthy server is silent: no output looks like a hang, while it is the correct behaviour of a stdio transport.

How to read the error

When the fix does not work

If the server starts but sees no components, the project may sit on a different path than the one expected: open the folder that holds components.json, not the monorepo parent. A second limit is permission. Some editors require you to approve MCP tools explicitly before they run, and without approval the server looks connected but never answers.

When the usual fix makes it worse

The quick fix writes the absolute path found in the terminal into the configuration file. It works on that machine and breaks the repository: a colleague on macOS inherits a C:\Program Files\nodejs\npx.cmd that does not exist, and the committed file becomes the cause of the next bug. The same holds for cmd /c npx pasted into a shared repository, and for adding -y with @latest: every start resolves the version over the network, so behind a slow proxy the first handshake outlives the editor timeout and the server looks broken while it is only downloading.

A named limitation

The documented limit of the stdio transport: the server inherits the environment of the editor, not of your shell. A variable exported in .zshrc or set with $env: in PowerShell never reaches the child process, so a private registry that needs a token connects and then rejects every request. The variable belongs in the env block of the MCP configuration, where the editor hands it to the process, and that block must not be committed with the secret inside.

How to prevent it

• Keep the MCP configuration in the repository when it is specific to the project.
• Document the Node version you require: the server tracks shadcn releases.
• Grant only the tools you need: an MCP server can read the project and propose changes to it.
• Check the configuration with the exact command the editor runs, not a similar one.

Where to go next

In the catalogue: components, blocks with preview and icons. The guides: MCP with shadcn in Claude Code, Cursor and VS Code and private registries and tokens. The comparison: copy-paste or headless.