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.

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:

bash

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

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

json

{
        "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):

bash

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:

json

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

Error Response:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

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

Error Response:

json

{
  "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:

json

{
  "status": "success",
  "content": [
    "posts/my-first-post.md",
    "posts/another-post.md",
    "pages/about.md"
  ]
}

Error Response:

json

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

Prerequisites: Hugo must be installed.

Actions After Success: A list of content files is returned.

Actions After Failure: No content is returned.

Preview and Build Tools

start_preview

Description: Start Hugo local server.

Parameters:

site_path: The path to the Hugo site.
port (optional): The port to use. Defaults to 1313.
bind (optional): The address to bind to. Defaults to "127.0.0.1".
build_drafts (optional): Whether to build draft content. Defaults to false.
build_future (optional): Whether to build future content. Defaults to false.
build_expired (optional): Whether to build expired content. Defaults to false.

Returns:

json

{
  "status": "success",
  "url": "http://127.0.0.1:1313",
  "pid": 12345,
  "options": {
    "build_drafts": false,
    "build_future": false,
    "build_expired": false
  }
}

Error Response:

json

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

Prerequisites: Hugo must be installed.

Actions After Success: The Hugo server is started and accessible at the specified URL.

Actions After Failure: The server is not started.

stop_preview

Description: Stop a running Hugo preview server.

Parameters:

pid: The process ID of the server to stop.

Returns:

json

{
  "status": "success",
  "message": "Server with PID 12345 stopped"
}

Error Response:

json

{
  "status": "error",
  "message": "Process with PID 12345 not found"
}

Prerequisites: None.

Actions After Success: The Hugo server is stopped.

Actions After Failure: The server is not stopped.

build_site

Description: Build the Hugo site for production.

Parameters:

site_path: The path to the Hugo site.
destination (optional): The destination directory. Defaults to "public".
clean_destination (optional): Whether to clean the destination directory before building. Defaults to false.
minify (optional): Whether to minify the output. Defaults to false.

Returns:

json

{
  "status": "success",
  "destination": "/path/to/site/public",
  "output": "Built in 123 ms"
}

Error Response:

json

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

Prerequisites: Hugo must be installed.

Actions After Success: The site is built and ready for deployment.

Actions After Failure: The site is not built.

deploy_site

Description: Deploy a Hugo site to various platforms.

Parameters:

site_path: The path to the Hugo site.
platform: Deployment platform (github-pages, netlify, vercel, custom).
destination (optional): Build destination directory. Defaults to "public".
branch (optional): Branch to deploy to. Defaults to "main".
commit_message (optional): Commit message for the deployment. Defaults to "Update site".
remote_url (optional): Remote URL for custom deployment.
api_key (optional): API key for the deployment platform.
additional_options (optional): Additional platform-specific options.

Returns:

json

{
  "status": "success",
  "platform": "github-pages",
  "branch": "gh-pages",
  "url": "https://username.github.io"
}

Error Response:

json

{
  "status": "error",
  "message": "Deployment failed: GitHub Pages deployment failed: Command 'git push origin gh-pages --force' returned non-zero exit status 1."
}

Prerequisites:

Hugo must be installed.
Git must be installed.
For GitHub Pages: Git repository must be initialized.
For Netlify: Netlify CLI must be installed (will be installed automatically if not present).
For Vercel: Vercel CLI must be installed (will be installed automatically if not present).

Actions After Success: The site is deployed to the specified platform and accessible at the returned URL.

Actions After Failure: The site is not deployed.

Platform-specific notes:

GitHub Pages: Requires a Git repository and optionally an API key for authentication.
Netlify: Requires Netlify CLI and optionally an API key for authentication.
Vercel: Requires Vercel CLI and optionally an API key for authentication.
Custom: Requires a Git repository and a remote URL.

Complete Workflow Example

Here's a complete workflow example (in python scripts rather than mcp server tools to show the common route) for creating a new Hugo site with a theme:

1. Check if Hugo is installed:

python

result = await check_hugo_installation()
   if result["status"] != "success":
       result = await install_hugo()

2. Check if Git is installed:

python

result = await check_git_installation()
   if result["status"] != "success":
       result = await install_git()

3. Configure Git:

python

result = await configure_git("John Doe", "john.doe@example.com")

4. List available themes:

python

result = await list_themes()
   themes = result["themes"]

5. Get details for a specific theme:

python

result = await get_theme_details("Paper")
   theme_details = result["theme"]

6. Create a new site with the theme:

python

result = await create_site("my-blog", theme="nanxiaobei/hugo-paper", use_example_site=True)
   site_path = result["path"]

7. Start the preview server:

python

result = await start_preview(site_path, build_drafts=True)
   preview_url = result["url"]

8. Create a new post:

python

result = await create_post(site_path, "my-first-post", draft=False)
   post_file = result["file"]

9. Build the site for production:

python

result = await build_site(site_path, minify=True)

10. Deploy the site to GitHub Pages:

python

result = await deploy_site(
        site_path=site_path,
        platform="github-pages",
        branch="gh-pages",
        commit_message="Deploy site",
        api_key="your-github-token"
    )
    deploy_url = result["url"]

Troubleshooting

Common Issues

1. Hugo is not installed:

Use the install_hugo tool to install Hugo.

2. Git is not installed:

Use the install_git tool to install Git.

3. Theme installation fails:

Check if the theme URL is correct.
Make sure Git is installed for git submodules.
Make sure Go is installed for Hugo modules.
Read the theme's doc to check if there is sth. different

4. Preview server fails to start:

Check if the port is already in use.
Make sure the site path is correct.
Check your network

5. Build fails:

Check if the site path is correct.
Make sure all required dependencies are installed.

Getting Help

If you encounter any issues not covered in this documentation, please open an issue on the GitHub repository.

Hugo Mcp

Documentation

Hugo MCP Server

Table of Contents

Installation

Prerequisites

Installing the Hugo MCP Server

Usage

Basic Usage

Tools

Environment Setup Tools

check_hugo_installation

install_hugo

check_go_installation

install_go

check_git_installation

install_git

configure_git

Site Management Tools

create_site

Theme Management Tools

list_themes

get_theme_details

install_theme

update_theme

Content Management Tools

create_post

list_content

Preview and Build Tools

start_preview

stop_preview

build_site

deploy_site

Complete Workflow Example

Troubleshooting

Common Issues

Getting Help

Similar MCP

Kill Process Mcp

Davinci Resolve Mcp

Fhir Mcp Server

Mcp Aoai Web Browsing

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Kill Process Mcp

Davinci Resolve Mcp

Fhir Mcp Server

Mcp Aoai Web Browsing

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare