Hugo MCP Server

A powerful MCP (Model Control Protocol) server for managing Hugo static site generator. This server provides a comprehensive set of tools for creating, managing, and deploying Hugo sites.

Table of Contents

• Installation
• Usage
• Tools
  • Environment Setup Tools
  • Site Management Tools
  • Theme Management Tools
  • Content Management Tools
  • Preview and Build Tools
• Complete Workflow Example
• Troubleshooting

Installation

Prerequisites

• Python 3.10+
• uv (Python package manager)
• Git (Highly recommended)

Installing the Hugo MCP Server

1. Clone the repository:

   git clone https://github.com/sunnycloudyang/hugo-mcp.git
   

2. Add server to your config (make sure uv has been installed before):

   {
        "mcpServers": {
            "hugo-mcp": {
                "command": "uv",
                "args": [
                    "--directory",
                    "/ABSOLUTE/PATH/TO/PARENT/FOLDER/hugo-mcp",
                    "run",
                    "main.py"
                ]
            }
        }
    }
   

   Remember to replace "/ABSOLUTE/PATH/TO/PARENT/FOLDER/hugo-mcp" to your installation path

3. Enalble this mcp server and try it!

Usage

The Hugo MCP server provides a set of tools that can be used to manage Hugo sites. Each tool has specific parameters and returns a structured response.

Basic Usage

1. Start the server manually (If needed):

   uv run main.py
   

2. Connect to the server using an MCP client.

3. Use the tools to manage your Hugo sites.

Tools

Environment Setup Tools

check_hugo_installation

Description: Check if Hugo is installed and get its version.

Parameters: None

Returns:

{
  "status": "success",
  "version": "Hugo Static Site Generator v0.92.0/extended linux/amd64 BuildDate=unknown"
}

Error Response:

{
  "status": "error",
  "message": "Hugo is not installed or not in PATH"
}

Prerequisites: None

Actions After Success: None

Actions After Failure: Install Hugo using the install_hugo tool.

install_hugo

Description: Install Hugo using the appropriate method for the current OS.

Parameters:

• version (optional): The version of Hugo to install. Defaults to "latest".

Returns:

{
  "status": "success",
  "message": "Hugo installed via Homebrew"
}

Error Response:

{
  "status": "error",
  "message": "Installation failed: Command 'brew install hugo' returned non-zero exit status 1."
}

Prerequisites: Appropriate package manager (Homebrew, apt, dnf, yum) must be installed.

Actions After Success: Hugo is installed and ready to use.

Actions After Failure: Manual installation may be required.

check_go_installation

Description: Check if Go is installed and get its version.

Parameters: None

Returns:

{
  "status": "success",
  "version": "go version go1.17.5 darwin/amd64"
}

Error Response:

{
  "status": "error",
  "message": "Go is not installed or not in PATH"
}

Prerequisites: None

Actions After Success: None

Actions After Failure: Install Go using the install_go tool.

install_go

Description: Install Go using the appropriate method for the current OS.

Parameters:

• version (optional): The version of Go to install. Defaults to "latest".

Returns:

{
  "status": "success",
  "message": "Go installed via Homebrew"
}

Error Response:

{
  "status": "error",
  "message": "Installation failed: Command 'brew install go' returned non-zero exit status 1."
}

Prerequisites: Appropriate package manager (Homebrew, apt, dnf, yum) must be installed.

Actions After Success: Go is installed and ready to use.

Actions After Failure: Manual installation may be required.

check_git_installation

Description: Check if Git is installed and get its configuration.

Parameters: None

Returns:

{
  "status": "success",
  "version": "git version 2.30.1 (Apple Git-130)",
  "user": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "default_branch": "main"
}

Error Response:

{
  "status": "error",
  "message": "Git is not installed or not in PATH"
}

Prerequisites: None

Actions After Success: None

Actions After Failure: Install Git using the install_git tool.

install_git

Description: Install Git using the appropriate method for the current OS.

Parameters: None

Returns:

{
  "status": "success",
  "message": "Git installed via Homebrew"
}

Error Response:

{
  "status": "error",
  "message": "Installation failed: Command 'brew install git' returned non-zero exit status 1."
}

Prerequisites: Appropriate package manager (Homebrew, apt, dnf, yum) must be installed.

Actions After Success: Git is installed and ready to use.

Actions After Failure: Manual installation may be required.

configure_git

Description: Configure Git with user name and email.

Parameters:

• name: The user name to set.
• email: The email address to set.

Returns:

{
  "status": "success",
  "message": "Git configured with name 'John Doe' and email 'john.doe@example.com'"
}

Error Response:

{
  "status": "error",
  "message": "Failed to configure Git: Command 'git config --global user.name John Doe' returned non-zero exit status 1."
}

Prerequisites: Git must be installed.

Actions After Success: Git is configured with the specified user name and email.

Actions After Failure: Manual configuration may be required.

Site Management Tools

create_site

Description: Create a new Hugo site.

Parameters:

• site_name: The name of the site to create.
• theme (optional): The theme to use for the site.
• force (optional): Whether to force creation if the directory already exists. Defaults to false.
• use_example_site (optional): Whether to use the example site from the theme. Defaults to true.

Returns:

{
  "status": "success",
  "path": "/path/to/site",
  "theme": "paper",
  "example_site": true,
  "author": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  }
}

Error Response:

{
  "status": "error",
  "message": "Directory 'site' already exists. Use force=True to overwrite."
}

Prerequisites: Hugo must be installed.

Actions After Success: A new Hugo site is created with the specified theme and example content.

Actions After Failure: The site is not created.

Theme Management Tools

list_themes

Description: List available Hugo themes from the official Hugo themes website.

Parameters: None

Returns:

{
  "status": "success",
  "themes": [
    {
      "name": "PaperMod",
      "url": "https://github.com/gohugoio/hugoThemes/tree/master/themes/hugo-papermod",
      "image": "https://themes.gohugo.io/themes/hugo-papermod/tn-featured_hu_275191178647f5e7.png"
    },
    {
      "name": "Hugo Blox - Tailwind",
      "url": "https://github.com/gohugoio/hugoThemes/tree/master/themes/blox-tailwind",
      "image": "https://themes.gohugo.io/themes/blox-tailwind/tn-featured_hu_8c1541d303ce3b9b.png"
    }
  ],
  "count": 150
}

Error Response:

{
  "status": "error",
  "message": "Network error: Connection refused"
}

Prerequisites: Internet connection.

Actions After Success: A list of available themes is returned.

Actions After Failure: No themes are returned.

get_theme_details

Description: Get detailed information about a specific Hugo theme.

Parameters:

• theme_name: The name of the theme to get details for.

Returns:

{
  "status": "success",
  "theme": {
    "name": "Paper",
    "url": "https://github.com/gohugoio/hugoThemes/tree/master/themes/paper",
    "image": "https://themes.gohugo.io/themes/paper/tn-featured.png",
    "description": "A simple, clean, and responsive Hugo theme for personal blog.",
    "features": [
      "Responsive design",
      "Clean and minimal",
      "Fast and lightweight",
      "SEO friendly"
    ],
    "tags": ["blog", "minimal", "responsive"],
    "github_url": "https://github.com/nanxiaobei/hugo-paper",
    "demo_url": "https://themes.gohugo.io/theme/paper/",
    "installation": "git submodule add https://github.com/nanxiaobei/hugo-paper themes/paper"
  }
}

Error Response:

{
  "status": "error",
  "message": "Theme 'NonExistentTheme' not found on the Hugo themes website"
}

Prerequisites: Internet connection.

Actions After Success: Detailed information about the theme is returned.

Actions After Failure: No theme details are returned.

install_theme

Description: Install a Hugo theme using git submodule or Hugo modules.

Parameters:

• site_path: The path to the Hugo site.
• theme_name: The name of the theme to install.
• theme_url: The URL of the theme repository.
• use_modules (optional): Whether to use Hugo modules instead of git submodules. Defaults to false.

Returns:

{
  "status": "success",
  "theme": "paper",
  "method": "git_submodule"
}

Error Response:

{
  "status": "error",
  "message": "Failed to install theme: Command 'git submodule add https://github.com/nanxiaobei/hugo-paper themes/paper' returned non-zero exit status 1."
}

Prerequisites:

• Hugo must be installed.
• Git must be installed (for git submodules).
• Go must be installed (for Hugo modules).

Actions After Success: The theme is installed and configured in the site.

Actions After Failure: The theme is not installed.

update_theme

Description: Update an installed Hugo theme.

Parameters:

• site_path: The path to the Hugo site.
• theme_name: The name of the theme to update.
• use_modules (optional): Whether the theme was installed using Hugo modules. Defaults to false.

Returns:

{
  "status": "success",
  "theme": "paper",
  "method": "git_submodule"
}

Error Response:

{
  "status": "error",
  "message": "Failed to update theme: Command 'git submodule update --remote themes/paper' returned non-zero exit status 1."
}

Prerequisites:

• Hugo must be installed.
• Git must be installed (for git submodules).
• Go must be installed (for Hugo modules).
• The theme must be already installed.

Actions After Success: The theme is updated to the latest version.

Actions After Failure: The theme is not updated.

Content Management Tools

create_post

Description: Create a new Hugo post.

Parameters:

• site_path: The path to the Hugo site.
• post_title: The title of the post.
• content_type (optional): The content type of the post. Defaults to "posts".
• draft (optional): Whether the post should be a draft. Defaults to true.
• date (optional): The date of the post.

Returns:

{
  "status": "success",
  "file": "content/posts/my-first-post.md",
  "draft": true
}

Error Response:

{
  "status": "error",
  "message": "Site path '/path/to/site' does not exist"
}

Prerequisites: Hugo must be installed.

Actions After Success: A new post is created in the specified content type directory.

Actions After Failure: The post is not created.

list_content

Description: List content in the Hugo site.

Parameters:

• site_path: The path to the Hugo site.
• content_type (optional): The content type to list. If not specified, all content is listed.

Returns:

{
  "status": "success",
  "content": [