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.
Clone the repository:
git clone https://github.com/sunnycloudyang/hugo-mcp.git
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
Enalble this mcp server and try it!
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.
Start the server manually (If needed):
uv run main.py
Connect to the server using an MCP client.
Use the tools to manage your Hugo sites.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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:
Actions After Success: The theme is installed and configured in the site.
Actions After Failure: The theme is not installed.
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:
Actions After Success: The theme is updated to the latest version.
Actions After Failure: The theme is not updated.
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.
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": [
"posts/my-first-post.md",
"posts/another-post.md",
"pages/about.md"
]
}
Error Response:
{
"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.
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:
{
"status": "success",
"url": "http://127.0.0.1:1313",
"pid": 12345,
"options": {
"build_drafts": false,
"build_future": false,
"build_expired": false
}
}
Error Response:
{
"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.
Description: Stop a running Hugo preview server.
Parameters:
pid: The process ID of the server to stop.Returns:
{
"status": "success",
"message": "Server with PID 12345 stopped"
}
Error Response:
{
"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.
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:
{
"status": "success",
"destination": "/path/to/site/public",
"output": "Built in 123 ms"
}
Error Response:
{
"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.
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:
{
"status": "success",
"platform": "github-pages",
"branch": "gh-pages",
"url": "https://username.github.io"
}
Error Response:
{
"status": "error",
"message": "Deployment failed: GitHub Pages deployment failed: Command 'git push origin gh-pages --force' returned non-zero exit status 1."
}
Prerequisites:
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:
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:
Check if Hugo is installed:
result = await check_hugo_installation()
if result["status"] != "success":
result = await install_hugo()
Check if Git is installed:
result = await check_git_installation()
if result["status"] != "success":
result = await install_git()
Configure Git:
result = await configure_git("John Doe", "john.doe@example.com")
List available themes:
result = await list_themes()
themes = result["themes"]
Get details for a specific theme:
result = await get_theme_details("Paper")
theme_details = result["theme"]
Create a new site with the theme:
result = await create_site("my-blog", theme="nanxiaobei/hugo-paper", use_example_site=True)
site_path = result["path"]
Start the preview server:
result = await start_preview(site_path, build_drafts=True)
preview_url = result["url"]
Create a new post:
result = await create_post(site_path, "my-first-post", draft=False)
post_file = result["file"]
Build the site for production:
result = await build_site(site_path, minify=True)
Deploy the site to GitHub Pages:
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"]
Hugo is not installed:
install_hugo tool to install Hugo.Git is not installed:
install_git tool to install Git.Theme installation fails:
Preview server fails to start:
Build fails:
If you encounter any issues not covered in this documentation, please open an issue on the GitHub repository.