Hugo MCP Server

Hugo MCP Server

一个强大的 MCP (模型控制协议) 服务器，用于管理 Hugo 静态站点生成器。

SunnyCloudYang

开发者工具
访问服务器

README

Hugo MCP 服务器

一个强大的 MCP (模型控制协议) 服务器，用于管理 Hugo 静态站点生成器。此服务器提供了一套全面的工具，用于创建、管理和部署 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 未安装或不在 PATH 中"
}

前提条件: 无

成功后的操作: 无

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

install_hugo

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

参数:

  • version (可选): 要安装的 Hugo 版本。默认为 "latest"。

返回值:

{
  "status": "success",
  "message": "Hugo 通过 Homebrew 安装"
}

错误响应:

{
  "status": "error",
  "message": "安装失败: 命令 'brew install hugo' 返回非零退出状态 1。"
}

前提条件: 必须安装适当的包管理器（Homebrew、apt、dnf、yum）。

成功后的操作: Hugo 已安装并可以使用。

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

check_go_installation

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

参数: 无

返回值:

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

错误响应:

{
  "status": "error",
  "message": "Go 未安装或不在 PATH 中"
}

前提条件: 无

成功后的操作: 无

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

install_go

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

参数:

  • version (可选): 要安装的 Go 版本。默认为 "latest"。

返回值:

{
  "status": "success",
  "message": "Go 通过 Homebrew 安装"
}

错误响应:

{
  "status": "error",
  "message": "安装失败: 命令 'brew install go' 返回非零退出状态 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": "john.doe@example.com"
  },
  "default_branch": "main"
}

错误响应:

{
  "status": "error",
  "message": "Git 未安装或不在 PATH 中"
}

前提条件: 无

成功后的操作: 无

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

install_git

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

参数: 无

返回值:

{
  "status": "success",
  "message": "Git 通过 Homebrew 安装"
}

错误响应:

{
  "status": "error",
  "message": "安装失败: 命令 'brew install git' 返回非零退出状态 1。"
}

前提条件: 必须安装适当的包管理器（Homebrew、apt、dnf、yum）。

成功后的操作: Git 已安装并可以使用。

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

configure_git

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

参数:

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

返回值:

{
  "status": "success",
  "message": "Git 配置为名称 'John Doe' 和电子邮件 'john.doe@example.com'"
}

错误响应:

{
  "status": "error",
  "message": "无法配置 Git: 命令 'git config --global user.name John Doe' 返回非零退出状态 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": "john.doe@example.com"
  }
}

错误响应:

{
  "status": "error",
  "message": "目录 'site' 已经存在。使用 force=True 覆盖。"
}

前提条件: 必须安装 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": "网络错误: 连接被拒绝"
}

前提条件: 互联网连接。

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

失败后的操作: 不返回任何主题。

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": "一个简单、干净且响应迅速的 Hugo 主题，适用于个人博客。",
    "features": [
      "响应式设计",
      "干净且极简",
      "快速且轻量级",
      "SEO 友好"
    ],
    "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": "在 Hugo 主题网站上找不到主题 'NonExistentTheme'"
}

前提条件: 互联网连接。

成功后的操作: 返回有关主题的详细信息。

失败后的操作: 不返回任何主题详细信息。

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": "无法安装主题: 命令 'git submodule add https://github.com/nanxiaobei/hugo-paper themes/paper' 返回非零退出状态 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": "无法更新主题: 命令 'git submodule update --remote themes/paper' 返回非零退出状态 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": "站点路径 '/path/to/site' 不存在"
}

前提条件: 必须安装 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": "站点路径 '/path/to/site' 不存在"
}

前提条件: 必须安装 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": "站点路径 '/path/to/site' 不存在"
}

前提条件: 必须安装 Hugo。

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

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

stop_preview

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

参数:

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

返回值:

{
  "status": "success",
  "message": "已停止 PID 为 12345 的服务器"
}

错误响应:

{
  "status": "error",
  "message": "找不到 PID 为 12345 的进程"
}

前提条件: 无。

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

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

build_site

描述: 构建用于生产的 Hugo 站点。

参数:

  • site_path: Hugo 站点的路径。
  • destination (可选): 目标目录。默认为 "public"。
  • clean_destination (可选): 是否在构建之前清理目标目录。默认为 false。
  • minify (可选): 是否缩小输出。默认为 false。

返回值:

{
  "status": "success",
  "destination": "/path/to/site/public",
  "output": "在 123 毫秒内构建"
}

错误响应:

{
  "status": "error",
  "message": "站点路径 '/path/to/site' 不存在"
}

前提条件: 必须安装 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": "部署失败: GitHub Pages 部署失败: 命令 'git push origin gh-pages --force' 返回非零退出状态 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", "john.doe@example.com")

  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 仓库上打开一个 issue。

推荐服务器

Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
MCP Package Docs Server

MCP Package Docs Server

促进大型语言模型高效访问和获取 Go、Python 和 NPM 包的结构化文档，通过多语言支持和性能优化来增强软件开发。

精选
本地
TypeScript
Claude Code MCP

Claude Code MCP

一个实现了 Claude Code 作为模型上下文协议（Model Context Protocol, MCP）服务器的方案，它可以通过标准化的 MCP 接口来使用 Claude 的软件工程能力（代码生成、编辑、审查和文件操作）。

精选
本地
JavaScript
@kazuph/mcp-taskmanager

@kazuph/mcp-taskmanager

用于任务管理的模型上下文协议服务器。它允许 Claude Desktop（或任何 MCP 客户端）在基于队列的系统中管理和执行任务。

精选
本地
JavaScript
mermaid-mcp-server

mermaid-mcp-server

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。

精选
JavaScript
Jira-Context-MCP

Jira-Context-MCP

MCP 服务器向 AI 编码助手（如 Cursor）提供 Jira 工单信息。

精选
TypeScript
Linear MCP Server

Linear MCP Server

一个模型上下文协议（Model Context Protocol）服务器，它与 Linear 的问题跟踪系统集成，允许大型语言模型（LLM）通过自然语言交互来创建、更新、搜索和评论 Linear 问题。

精选
JavaScript
Sequential Thinking MCP Server

Sequential Thinking MCP Server

这个服务器通过将复杂问题分解为顺序步骤来促进结构化的问题解决，支持修订，并通过完整的 MCP 集成来实现多条解决方案路径。

精选
Python
Curri MCP Server

Curri MCP Server

通过管理文本笔记、提供笔记创建工具以及使用结构化提示生成摘要，从而实现与 Curri API 的交互。

官方
本地
JavaScript