# Checklist.design MCP for Codex

An unofficial, read-only [Model Context Protocol](https://modelcontextprotocol.io/) server that puts the public [Checklist.design](https://www.checklist.design) catalogue inside Codex and other MCP clients.

I kept opening Checklist.design while building interfaces. It is a useful reference for the small UX details that are easy to miss, so I made the checklists searchable from the place where I was already working.

Ask for a mobile checkout checklist, a subscription-cancellation flow, or guidance for an admin billing screen. The MCP searches 110 UX and UI design checklists and returns the relevant source material with attribution.

The server runs locally. It does not need an API key, call the paid Checklist.design AI checker, upload your designs, or write to any external service.

> This repository contains code and synthetic test fixtures only. Checklist.design content is fetched into each user's local cache and remains owned by Checklist Design Pty Ltd. See [Third-party content](#third-party-content).

## Add it to Codex

Run:

```bash
codex mcp add design_checklists -- npx -y github:patelchanakya/design-checklists-mcp
```

Start a new Codex task, then check the connection:

```bash
codex mcp list
```

The first launch downloads the public catalogue to a local cache. Later launches read that cache and start without another network request.

Try asking Codex:

```text
Use design_checklists to find everything relevant to a mobile checkout.
Get the complete flows/canceling-subscription checklist.
Build a review checklist for an admin billing screen with 2FA.
```

For another MCP client, use `npx` as the command and these arguments:

```json
{
  "command": "npx",
  "args": ["-y", "github:patelchanakya/design-checklists-mcp"]
}
```

## What you get

| Tool | What it does |
| --- | --- |
| `get_catalog_summary` | Returns source metadata plus checklist, entry, and category totals. |
| `list_checklists` | Browses and filters checklist summaries. |
| `search_checklists` | Searches checklist names, descriptions, suggestions, and step text. |
| `get_checklist` | Returns one complete checklist by `category/slug`, slug, or UUID. |
| `build_review_checklist` | Selects a focused set of checklists for a screen, component, or flow. |

All five tools are read-only, idempotent, and non-destructive. Search and review selection are deterministic local keyword matching, not an AI design review.

## Run it from source

```bash
git clone https://github.com/patelchanakya/design-checklists-mcp.git
cd design-checklists-mcp
npm ci
npm test
codex mcp add design_checklists -- node "$PWD/src/server.mjs"
```

The repository also includes a project-scoped `.codex/config.toml` for development.

## Local cache

- First launch fetches the public catalogue and validates every checklist before saving it.
- Later launches use the saved cache.
- `npx -y github:patelchanakya/design-checklists-mcp --sync` refreshes it manually.
- `CHECKLIST_DESIGN_DATA_PATH=/absolute/path/checklists.json` changes the cache location.
- `npm run sync` writes an ignored development snapshot to `data/checklists.json`.

The importer uses bounded concurrency and replaces the cache only after the complete download passes validation. MCP diagnostics go to stderr so stdout stays reserved for protocol messages.

## Scope

These checklists are reference material. A returned checklist does not prove accessibility, platform compliance, user validation, or production correctness. The public Checklist.design endpoints can also change; run `--sync` when you want a fresh local copy.

The MCP does not access the paid Figma or AI analysis service.

## Third-party content

The MIT licence covers this project's code, documentation, and synthetic tests. It does not cover Checklist.design names, descriptions, checklist entries, suggestions, images, branding, plugin, or paid services.

Checklist content is retrieved for local use and returned with attribution to Checklist Design. Use remains subject to the [Checklist.design Terms of Service](https://www.checklist.design/terms).

This project is independent and unofficial. Do not publish generated cache files or represent the project as an official Checklist.design product without explicit written permission.

## Contributing

Issues and small pull requests are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for the test and content rules. Security reports belong in a private GitHub security advisory; see [SECURITY.md](SECURITY.md).

The source code is available under the [MIT Licence](LICENSE).