GOV.UK Design System MCP

TypeScript MCP server that serves locally-crawled GOV.UK Design System guidance from SQLite FTS5.

Features

• Manual crawler restricted to approved GOV.UK Design System sections.
• SQLite-backed storage at data/govuk-design-system.db.
• FTS5 search with deterministic ranking and snippets.
• MCP tools:
• search(query: string)
• fetch(id: string)
• version()
• STDIO transport adapter isolated from core logic.

Setup

bun install
cp .env.example .env

Build the Local Dataset

bun run crawl

Run MCP Server

bun run start

Add This MCP to Developer Tools

The server uses STDIO transport, so most MCP-compatible tools can run it with a command.

Use this command in your MCP client configuration:

bun run /absolute/path/to/govuk-frontend-mcp/src/index.ts

If your client supports separate command and args, use:

• command: bun
• args: ["run", "/absolute/path/to/govuk-frontend-mcp/src/index.ts"]
• cwd: /absolute/path/to/govuk-frontend-mcp

Example: Claude Code (MCP config)

{
  "mcpServers": {
    "govuk-design-system": {
      "command": "bun",
      "args": [
        "run",
        "/absolute/path/to/govuk-frontend-mcp/src/index.ts"
      ],
      "cwd": "/absolute/path/to/govuk-frontend-mcp"
    }
  }
}

Example: Cursor / VS Code style MCP config

∏
  "mcpServers": {
    "govuk-design-system": {
      "type": "stdio",
      "command": "bun",
      "args": [
        "run",
        "/absolute/path/to/govuk-frontend-mcp/src/index.ts"
      ],
      "cwd": "/absolute/path/to/govuk-frontend-mcp"
    }
  }
}

Example: Docker command for clients that run shell commands

docker compose run --rm govuk-design-system-mcp bun run src/index.ts

After connecting, the MCP should expose:

• search(query: string)
• fetch(id: string)
• version()

Tip: run bun run crawl whenever you want to refresh the local GOV.UK data before using the MCP in your tool.

Docker Compose

docker compose up --build

Test

bun test
bun run typecheck