Client Setup

Install the design.md MCP server in Claude Code, Cursor, Codex, or Cline.

Install the server

First, install the MCP package globally:

npm install -g @webdesignhot/design-md-mcp
pnpm add -g @webdesignhot/design-md-mcp
yarn global add @webdesignhot/design-md-mcp
bun add -g @webdesignhot/design-md-mcp

Once installed, the design-md-mcp binary will be in your system’s global npm directory (usually ~/.npm or /usr/local/bin).

Configure your client

Now add an MCP config entry pointing at the binary. The config file and format differ by client.

Claude Code

Config file: ~/.config/claude-code/mcp.json

Alternatively, you can use the Claude Code UI: Settings → MCP Servers and add the server there.

{
  "mcpServers": {
    "design-md": {
      "command": "design-md-mcp",
      "args": []
    }
  }
}

After saving, restart Claude Code or reload the MCP configuration.

Cursor

Config file: ~/.cursor/mcp.json

{
  "mcpServers": {
    "design-md": {
      "command": "design-md-mcp",
      "args": []
    }
  }
}

After saving, restart Cursor completely (close and reopen).

Codex

Config file: ~/.codex/config.toml

[mcp_servers.design-md]
command = "design-md-mcp"
args = []

After saving, restart Codex.

Cline

Open Cline settings → MCP Servers.

Click + Add MCP Server and fill in:

  • Server Name: design-md
  • Command: design-md-mcp
  • Arguments: (leave empty)

Click Add and restart Cline or reload the settings.

Verify

After restarting your editor, the design.md MCP server should be active. Verify it appears in your agent’s tool list:

In Claude Code, open the agent panel (or start typing a prompt). The MCP tools appear in the Tools section. You should see:

  • list_designs
  • get_design
  • search_designs
  • diff_designs
  • export_design
  • install_design

In Cursor, open the Agent panel or @-mention the agent. The MCP tools appear in the agent’s available tools list.

In Codex, open the Agent dashboard. The MCP tools appear under Available Tools.

In Cline, open the Tools section of the Cline panel. The design.md tools should appear alongside any other MCP servers you have configured.

If the tools don’t appear, see Troubleshooting below.

Troubleshooting

”design-md-mcp: command not found”

The npm global binary is not in your system PATH. Check your global npm directory:

npm config get prefix
# /usr/local/bin (or ~/.npm, or ~/.nvm/versions/node/v20.0.0/bin, etc.)

Make sure that directory is in your $PATH:

echo $PATH

If the global npm directory is missing from $PATH, add it to your shell profile (~/.bashrc, ~/.zshrc, etc.):

export PATH="$(npm config get prefix)/bin:$PATH"

Then restart your terminal and reinstall:

npm install -g @webdesignhot/design-md-mcp

“MCP server not appearing in tools”

  1. Restart your editor completely. A partial reload is not enough; close and reopen.
  2. Check the config file path. The file must be in the exact location:
    • Claude Code: ~/.config/claude-code/mcp.json
    • Cursor: ~/.cursor/mcp.json
    • Codex: ~/.codex/config.toml
    • Cline: via Settings UI
  3. Verify the JSON/TOML is valid. Use a JSON/TOML linter if the editor doesn’t show syntax errors.
  4. Check that design-md-mcp is executable. Run: 
    design-md-mcp --version
    If this fails, npm installation didn’t complete; try reinstalling.

”Permission denied”

npm global installs sometimes have permission issues. Fix it with:

npm install -g @webdesignhot/design-md-mcp --no-optional

If that still fails, use sudo as a last resort (not recommended):

sudo npm install -g @webdesignhot/design-md-mcp

Then verify:

design-md-mcp --version

Server installed but not working in agent loops

  • Make sure your editor is actually using the agent. Some editor modes don’t enable the agent by default.
  • Prompt the agent to use the tools. MCP tools are available but not forced. Try: “What brands are in the design.md catalog? Use the MCP tools to check.”
  • Check editor logs. Claude Code (and others) log MCP errors. Look in the editor’s debug output or error panel.