Hugo MCP Remote Server

Streamable HTTP MCP server that wraps the Hugo Generator API. Use it from Cursor (or any MCP remote client) to add and manage page schemas, records, generate markdown, build, and publish.

Prerequisites

• Node.js 22+
• A running Hugo Generator API (HUGO_API_BASE_URL)

Local development

cp .env.example .env
# edit HUGO_API_BASE_URL if needed

npm install
npm run dev

Server listens on http://localhost:3100/mcp by default.

npm run build && npm start

Docker

docker compose up --build -d

Defaults:

Variable	Default
PORT	3100
HUGO_API_BASE_URL	http://host.docker.internal:8080
MCP_API_KEY	(empty — auth disabled)

extra_hosts: host.docker.internal:host-gateway lets the container reach an API on the host machine. If the API runs in the same Compose network, set HUGO_API_BASE_URL to that service URL instead (e.g. http://hugo-generator:8080).

Cursor MCP config

Add a remote server entry (path may vary by Cursor version):

{
  "mcpServers": {
    "hugo": {
      "url": "http://localhost:3100/mcp"
    }
  }
}

With optional bearer auth (MCP_API_KEY set on the server):

{
  "mcpServers": {
    "hugo": {
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer change-me"
      }
    }
  }
}

Tools

Tool	Purpose
health	Upstream API health
list_schemas / get_schema / upsert_schema / delete_schema / import_schema	Schema CRUD
list_records / get_record / create_record / list_registry	Page records
generate_page / generate_from_records	Write Hugo markdown
build_site	Run Hugo CLI
publish_site	Sync public/ to R2 via publisher
list_themes / get_theme / get_selected_theme / import_theme / select_theme / delete_theme	Theme library
scan_theme_signals / suggest_theme_schemas / apply_theme_schemas	Theme → schema helpers

Typical content workflow: list_schemas → create_record → generate_from_records → build_site → publish_site.

Note: The upstream Records API supports create/list/get only (no update/delete).

Environment

Variable	Required	Description
HUGO_API_BASE_URL	yes	Hugo Generator API base URL (no trailing slash)
PORT	no	Listen port (default 3100)
MCP_API_KEY	no	When set, /mcp requires Authorization: Bearer <key>

GET /health on this server is always unauthenticated (for Docker healthchecks).