mcp-uxhints

MCP (Model Context Protocol) server that exposes the uxhints.com catalog of bite-sized UX and product-design hints as MCP tools over stdio. Content comes from the site's public WordPress REST API (converted to clean Markdown), served through a local cache so tool calls are instant and work offline.

Install with npx (recommended)

Prerequisite: Node.js 18 or newer. No build step — npx downloads and runs the published package, and the bundled catalog snapshot lets the first tool call work with zero network.

Register the server in your MCP client, then restart the client.

OpenCode

Add to opencode.json:

{
  "mcp": {
    "mcp-uxhints": {
      "type": "local",
      "command": ["npx", "-y", "mcp-uxhints"],
      "enabled": true
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "mcp-uxhints": {
      "command": "npx",
      "args": ["-y", "mcp-uxhints"]
    }
  }
}

Note: do not run npx mcp-uxhints from inside your own clone of this repository — npm resolves the local package.json and fails with command not found. Any other directory works.

Related MCP server: mcp-maintainer-toolkit

Install from source (alternative)

For development or pinning a local build:

git clone https://github.com/Mateodioev/mcp-uxhints.git
cd mcp-uxhints
npm install && npm run build

Then point your client at the built file instead of npx:

• OpenCode: "command": ["node", "/absolute/path/mcp-uxhints/build/index.js"]

• Claude Desktop: "command": "node", "args": ["/absolute/path/mcp-uxhints/build/index.js"]

Tools

Typical flow: list_categories → list_hints → get_hint. Slugs never include the category prefix (occams-razor-law-in-ux-design, not ux-laws/occams-razor-law-in-ux-design).

Caching

Tool calls read from a local catalog cache (default TTL 24h) instead of hitting the API every time. Resolution order:

Not fresh? Call refresh_hint_catalog, or wait for the TTL to expire. A postinstall hook warms the user cache automatically when the bundled snapshot has expired since publish.

¹ ~/.cache/mcp-uxhints on Linux (honors XDG_CACHE_HOME), ~/Library/Caches/mcp-uxhints on macOS, %LOCALAPPDATA%\mcp-uxhints\Cache on Windows.

Details

Credit

All content © uxhints.com by Paul Capcan. This server only wraps the site's public API; it does not host or modify the content.