Hugo MCP Server

Hugo MCP 服务

用于管理 Hugo 静态站点生成器的强大 MCP（Model Control Protocol）服务。该服务提供一套全面的工具，用于创建、管理和部署 Hugo 站点。

目录

• 安装
• 使用方法
• 工具
  • 环境设置工具
  • 站点管理工具
  • 主题管理工具
  • 内容管理工具
  • 预览和构建工具
• 完整工作流示例
• 故障排除

安装

前提条件

• Python 3.10+
• uv（Python 包管理器）
• Git（强烈推荐）

安装 Hugo MCP 服务

1. 克隆仓库：

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

2. 将服务添加到配置中（请先确保已安装 uv）：

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

   请记得将 "/ABSOLUTE/PATH/TO/PARENT/FOLDER/hugo-mcp" 替换为你的安装路径

3. 启用此 MCP 服务并试用！

使用方法

Hugo MCP 服务提供一组可用于管理 Hugo 站点的工具。每个工具都有特定的参数，并会返回结构化响应。

基本用法

1. 手动启动服务（如有需要）：

   uv run main.py
   

2. 使用 MCP 客户端连接到服务。

3. 使用这些工具管理你的 Hugo 站点。

工具

环境设置工具

check_hugo_installation

描述：检查是否已安装 Hugo，并获取其版本。

参数：无

返回：

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

错误响应：

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

前提条件：无

成功后的操作：无

失败后的操作：使用 install_hugo 工具安装 Hugo。

install_hugo

描述：使用适用于当前操作系统的方法安装 Hugo。

参数：

• version（可选）：要安装的 Hugo 版本。默认为 "latest"。

返回：

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

错误响应：

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

前提条件：必须安装相应的包管理器（Homebrew、apt、dnf、yum）。

成功后的操作：Hugo 已安装并可供使用。

失败后的操作：可能需要手动安装。

check_go_installation

描述：检查是否已安装 Go，并获取其版本。

参数：无

返回：

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

错误响应：

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

前提条件：无

成功后的操作：无

失败后的操作：使用 install_go 工具安装 Go。

install_go

描述：使用适用于当前操作系统的方法安装 Go。

参数：

• version（可选）：要安装的 Go 版本。默认为 "latest"。

返回：

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

错误响应：

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

前提条件：必须安装相应的包管理器（Homebrew、apt、dnf、yum）。

成功后的操作：Go 已安装并可供使用。

失败后的操作：可能需要手动安装。

check_git_installation

描述：检查是否已安装 Git，并获取其配置。

参数：无

返回：

{
  "status": "success",
  "version": "git version 2.30.1 (Apple Git-130)",
  "user": {
    "name": "John Doe",
    "email": "[email protected]"
  },
  "default_branch": "main"
}

错误响应：

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

前提条件：无

成功后的操作：无

失败后的操作：使用 install_git 工具安装 Git。

install_git

描述：使用适用于当前操作系统的方法安装 Git。

参数：无

返回：

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

错误响应：

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

前提条件：必须安装相应的包管理器（Homebrew、apt、dnf、yum）。

成功后的操作：Git 已安装并可供使用。

失败后的操作：可能需要手动安装。

configure_git

描述：使用用户名和电子邮件配置 Git。

参数：

• name：要设置的用户名。
• email：要设置的电子邮件地址。

返回：

{
  "status": "success",
  "message": "Git configured with name 'John Doe' and email '[email protected]'"
}

错误响应：

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

先决条件：必须安装 Git。

成功后的操作：Git 已配置为指定的用户名和电子邮件。

失败后的操作：可能需要手动配置。

站点管理工具

create_site

描述：创建新的 Hugo 站点。

参数：

• site_name：要创建的站点名称。
• theme（可选）：站点要使用的主题。
• force（可选）：目录已存在时是否强制创建。默认为 false。
• use_example_site（可选）：是否使用主题中的示例站点。默认为 true。

返回：

{
  "status": "success",
  "path": "/path/to/site",
  "theme": "paper",
  "example_site": true,
  "author": {
    "name": "John Doe",
    "email": "[email protected]"
  }
}

错误响应：

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

先决条件：必须安装 Hugo。

成功后的操作：已创建一个使用指定主题并包含示例内容的新 Hugo 站点。

失败后的操作：未创建站点。

主题管理工具

list_themes

描述：列出 Hugo 官方主题网站上的可用 Hugo 主题。

参数：无

返回：

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

错误响应：

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

先决条件：需要互联网连接。

成功后的操作：返回可用主题列表。

失败后的操作：未返回任何主题。

get_theme_details

描述：获取特定 Hugo 主题的详细信息。

参数：

• theme_name：要获取详细信息的主题名称。

返回：

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

错误响应：

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

先决条件：需要互联网连接。

成功后的操作：返回主题的详细信息。

失败后的操作：未返回任何主题详情。

install_theme

描述：使用 Git 子模块或 Hugo 模块安装 Hugo 主题。

参数：

• site_path：Hugo 站点的路径。
• theme_name：要安装的主题名称。
• theme_url：主题仓库的 URL。
• use_modules（可选）：是否使用 Hugo 模块而非 Git 子模块。默认为 false。

返回：

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

错误响应：

{
  "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."
}

先决条件：

• 必须安装 Hugo。
• 必须安装 Git（用于 Git 子模块）。
• 必须安装 Go（用于 Hugo 模块）。

成功后的操作：主题已安装并配置到站点中。

失败后的操作：未安装主题。

update_theme

描述：更新已安装的 Hugo 主题。

参数：

• site_path：Hugo 站点的路径。
• theme_name：要更新的主题名称。
• use_modules（可选）：主题是否通过 Hugo 模块安装。默认为 false。

返回：

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

错误响应：

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

先决条件：

• 必须安装 Hugo。
• 必须安装 Git（用于 Git 子模块）。
• 必须安装 Go（用于 Hugo 模块）。
• 必须已安装主题。

成功后的操作：主题已更新至最新版本。

失败后的操作：未更新主题。

内容管理工具

create_post

描述：创建新的 Hugo 文章。

参数：

• site_path：Hugo 站点的路径。
• post_title：文章标题。
• content_type（可选）：文章的内容类型。默认为 "posts"。
• draft（可选）：文章是否应为草稿。默认为 true。
• date（可选）：文章日期。

返回：

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

错误响应：

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

先决条件：必须安装 Hugo。

成功后的操作：已在指定的内容类型目录中创建新文章。

失败后的操作：未创建文章。

list_content

描述：列出 Hugo 站点中的内容。

参数：

• site_path：Hugo 站点的路径。
• content_type（可选）：要列出的内容类型。未指定时，将列出所有内容。

返回：

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

错误响应：

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

前提条件：必须安装 Hugo。

成功后的操作：返回内容文件列表。

失败后的操作：不返回任何内容。

预览和构建工具

start_preview

描述：启动 Hugo 本地服务器。

参数：

• site_path：Hugo 站点的路径。
• port（可选）：要使用的端口。默认为 1313。
• bind（可选）：要绑定的地址。默认为 "127.0.0.1"。
• build_drafts（可选）：是否构建草稿内容。默认为 false。
• build_future（可选）：是否构建未来内容。默认为 false。
• build_expired（可选）：是否构建已过期内容。默认为 false。

返回：

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

错误响应：

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

前提条件：必须安装 Hugo。

成功后的操作：Hugo 服务器已启动，可通过指定的 URL 访问。

失败后的操作：服务器未启动。

stop_preview

描述：停止正在运行的 Hugo 预览服务器。

参数：

• pid：要停止的服务器的进程 ID。

返回：

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

错误响应：

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

前提条件：无。

成功后的操作：Hugo 服务器已停止。

失败后的操作：服务器未停止。

build_site

描述：构建用于生产环境的 Hugo 站点。

参数：

• site_path：Hugo 站点的路径。
• destination（可选）：目标目录。默认为 "public"。
• clean_destination（可选）：构建前是否清理目标目录。默认为 false。
• minify（可选）：是否压缩输出内容。默认为 false。

返回：

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

错误响应：

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

前提条件：必须安装 Hugo。

成功后的操作：站点已构建完成，可供部署。

失败后的操作：站点未构建。

deploy_site

描述：将 Hugo 站点部署到各种平台。

参数：

• site_path：Hugo 站点的路径。
• platform：部署平台（github-pages、netlify、vercel、custom）。
• destination（可选）：构建目标目录。默认为 "public"。
• branch（可选）：要部署到的分支。默认为 "main"。
• commit_message（可选）：部署提交信息。默认为 "Update site"。
• remote_url（可选）：自定义部署的远程 URL。
• api_key（可选）：部署平台的 API 密钥。
• additional_options（可选）：平台专属的其他选项。

返回：

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

错误响应：

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

前提条件：

• 必须安装 Hugo。
• 必须安装 Git。
• 对于 GitHub Pages：必须已初始化 Git 仓库。
• 对于 Netlify：必须安装 Netlify CLI（若尚未安装，将自动安装）。
• 对于 Vercel：必须安装 Vercel CLI（若尚未安装，将自动安装）。

成功后的操作：站点已部署到指定平台，可通过返回的 URL 访问。

失败后的操作：站点未部署。

平台专属说明：

• GitHub Pages：需要 Git 仓库，可选提供 API 密钥进行身份验证。
• Netlify：需要 Netlify CLI，可选提供 API 密钥进行身份验证。
• Vercel：需要 Vercel CLI，可选提供 API 密钥进行身份验证。
• Custom：需要 Git 仓库和远程 URL。

完整工作流示例

以下是一个使用 Python 脚本而非 MCP 服务工具展示常见路径的完整工作流示例，用于创建一个带主题的新 Hugo 站点：

1. 检查是否已安装 Hugo：

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

2. 检查是否已安装 Git：

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

3. 配置 Git：

   result = await configure_git("John Doe", "[email protected]")
   

4. 列出可用主题：

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

5. 获取特定主题的详细信息：

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

6. 使用该主题创建新站点：

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

7. 启动预览服务：

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

8. 创建新文章：

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

9. 构建用于生产环境的站点：

   result = await build_site(site_path, minify=True)
   

10. 将站点部署到 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"]
    

故障排除

常见问题

1. 未安装 Hugo：

   • 使用 install_hugo 工具安装 Hugo。

2. 未安装 Git：

   • 使用 install_git 工具安装 Git。

3. 主题安装失败：

   • 检查主题 URL 是否正确。
   • 确保已安装 Git，以便使用 Git 子模块。
   • 确保已安装 Go，以便使用 Hugo 模块。
   • 阅读主题文档，检查是否有不同之处。

4. 预览服务启动失败：

   • 检查端口是否已被占用。
   • 确保站点路径正确。
   • 检查网络连接。

5. 构建失败：

   • 检查站点路径是否正确。
   • 确保已安装所有必需的依赖项。

获取帮助

如果遇到本文档未涵盖的问题，请在 GitHub 仓库中提交问题。