Prototype Kit MCP Server

An MCP server that creates and manages GOV.UK Prototype Kit projects. Agents can scaffold kits, plan and generate multi-page journeys as Nunjucks macros, manage version folders, and run npm run dev — following the embedded AI guidelines in ai-context.md (GOV.UK Design System conventions, content design, and accessibility).

Getting started

Prerequisites

• Python 3.12+

• Node.js LTS (required for npx govuk-prototype-kit create and npm run dev)

• uv recommended

1. Install the server

git clone <your-repo-url> prototypekit-mcp
cd prototypekit-mcp
make install                 # creates .venv, installs deps + pre-commit hooks
cp .env.example .env

Optional: edit .env and set where prototypes should be created:

PROTOTYPE_ROOT=~/Documents/prototypes
PROTOTYPE_DEFAULT_PORT=3000
ENABLE_AUTH=False

2. Run the MCP server

make local                   # http://localhost:5001

Check it is up:

curl http://localhost:5001/health

uv venv && source .venv/bin/activate
uv pip install -e ".[dev]"
cp .env.example .env
prototypekit-mcp

3. Connect Cursor

Add this to your Cursor MCP settings (replace paths with your machine):

{
  "mcpServers": {
    "prototypekit": {
      "command": "/Users/YOU/Documents/prototypekit-mcp/.venv/bin/prototypekit-mcp",
      "env": {
        "ENABLE_AUTH": "False",
        "COMPATIBLE_WITH_CURSOR": "True",
        "PROTOTYPE_ROOT": "/Users/YOU/Documents/prototypes",
        "MCP_HOST": "localhost",
        "MCP_PORT": "5001"
      }
    }
  }
}

If the server is already running via make local, you can point Cursor at the HTTP endpoint instead: http://localhost:5001/mcp.

Restart Cursor (or reload MCP servers) and confirm the prototypekit tools appear.

4. Create your first prototype

In Cursor chat, ask the agent to use the tools, for example:

Using the prototypekit MCP tools: create a prototype named juggling-licence for “Apply for a juggling licence”, plan a journey that asks how many balls you can juggle, generate it as v1, then start it.

The agent should roughly:

1. get_ai_guidelines — load GOV.UK / ai-context rules

2. create_prototype — scaffold the kit under PROTOTYPE_ROOT

3. plan_journey → generate_journey — write app/views/v1/ pages and routes

4. start_prototype — open http://localhost:3000

Then open the returned URL in a browser. Later iterations: create_version, create_page, add_route.

For a step-by-step page example, see the tutorial.

Related MCP server: jt-mcp-server

MCP tools

Generators emit only Nunjucks macros and govuk-* classes. Unsupported custom UI returns an explicit gap error (ai-context rule 5).

Configuration

AI guidelines

The server ships prototypekit_mcp/src/assets/ai-context.md based on HM Land Registry / MoJ GOV.UK Prototype Kit AI context. Every new prototype receives a copy at {prototype}/ai-context.md.

Core rules enforced by generators:

1. Pages extend layouts/main.html

2. Use Nunjucks macros (govukButton, govukInput, …)

3. Only GOV.UK classes — no custom CSS

4. Accessibility via Design System components

5. Flag gaps when something is not possible with existing components

Documentation

License

Apache 2.0