Hugo MCP Server: Connecting Claude.ai to a Static Hugo Site

⚡ In short

Connect Claude.ai to a Hugo site hosted in a KVM VM in 30 minutes: a FastAPI server exposes 6 MCP tools (read, create, modify, delete pages, rebuild the site) via JSON-RPC 2.0, an OAuth proxy reuses existing infrastructure, and every modification automatically triggers a Hugo rebuild + Cloudflare cache purge.

The code is available on GitHub:

• 🔌 Hugo MCP Server: jmrGrav/hugo-mcp
• 🔐 OAuth Proxy: jmrGrav/mcp-oauth-proxy

🧠 Why

Anthropic’s MCP (Model Context Protocol) allows Claude.ai to connect to external data sources via standardized tools. Unlike Grav CMS which is dynamic (PHP), Hugo generates pure static HTML — making content management via MCP even more powerful: every modification is compiled and deployed instantly.

This homelab stack enables:

• Creating and modifying Hugo pages directly from Claude.ai without manually editing Markdown files
• Automatically rebuilding the site after every modification via hugo --minify
• Purging the Cloudflare cache in a targeted way after each change
• Managing bilingual content (FR + EN) in a single conversation

🔧 What was done

🏗️ Global architecture

        Claude.ai
            │
            │ HTTPS (OAuth 2.1 + PKCE)
            ▼
    ┌───────────────┐
    │  Cloudflare   │  WAF + Cache
    └───────┬───────┘
            │
            ▼
    ┌───────────────┐
    │     nginx     │  SSL termination
    │mcp-hugo.arleo │  location /mcp → proxy
    └───────┬───────┘
            │
            ▼
    ┌───────────────┐
    │ FastAPI proxy │  Port 8084 (NUC host)
    │  OAuth 2.1    │  Token validation
    │  mcp-proxy    │  SHA-256 hashing
    └───────┬───────┘
            │
            ▼
    ┌───────────────┐
    │  hugo-mcp     │  Port 8000 (KVM VM)
    │  FastAPI      │  6 MCP tools
    │  Python 3.12  │  192.168.122.69
    └───────┬───────┘
            │
    ┌───────┴────────┐
    ▼                ▼
~/hugo-site/    deploy.sh → /var/www/hugo
content/*.md    + Cloudflare purge

📦 Components

🔌 Step 1 — Install hugo-mcp in the VM

# Clone the repo in the VM
git clone https://github.com/jmrGrav/hugo-mcp.git ~/hugo-mcp
cd ~/hugo-mcp

# Create the Python virtual environment
sudo apt install -y python3.12-venv
python3 -m venv venv
venv/bin/pip install -r requirements.txt

# Generate the MCP token
MCP_TOKEN=$(openssl rand -hex 32)

# Configure secrets
cat > .env << EOF
MCP_TOKEN=$MCP_TOKEN
CF_TOKEN=<your_cloudflare_token>
CF_ZONE_ID=<your_zone_id>
EOF

# Install the systemd service
sudo cp systemd/hugo-mcp.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable --now hugo-mcp

# Verify
curl -s http://localhost:8000/health

🔐 Step 2 — Configure the OAuth proxy on the host

The OAuth proxy reuses mcp-oauth-proxy already installed for Grav, as an independent second instance on port 8084:

# Create Hugo MCP secrets
sudo mkdir -p /etc/hugo-mcp
sudo tee /etc/hugo-mcp/secrets.env << EOF
HUGO_MCP_URL=http://192.168.122.69:8000
HUGO_MCP_TOKEN=$MCP_TOKEN
MCP_CLIENT_ID=hugo-mcp
MCP_CLIENT_SECRET=$(openssl rand -hex 32)
TOKEN_SECRET=$(openssl rand -hex 32)
PROXY_PORT=8084
PROXY_BASE_URL=https://mcp-hugo.your-domain.com
EOF
sudo chmod 600 /etc/hugo-mcp/secrets.env

# Open port 8000 in the VM firewall
# only from the NUC host
sudo ufw allow from 192.168.122.1 to any port 8000 proto tcp

# Install and start the proxy service
sudo systemctl enable --now hugo-mcp-proxy

🌐 Step 3 — Configure nginx

server {
    listen 443 ssl http2;
    server_name mcp-hugo.your-domain.com;

    include snippets/ssl.conf;

    location /mcp {
        proxy_pass http://127.0.0.1:8084/mcp;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /.well-known/oauth-authorization-server {
        proxy_pass http://127.0.0.1:8084/.well-known/oauth-authorization-server;
        proxy_set_header Host $host;
    }

    location /oauth/ {
        proxy_pass http://127.0.0.1:8084/oauth/;
        proxy_set_header Host $host;
    }
}

🤝 Step 4 — Connect Claude.ai

1. Go to claude.ai → Settings → Connectors
2. Click Add connector
3. Enter the URL: https://mcp-hugo.your-domain.com/mcp
4. Follow the OAuth flow — authorize access
5. The 6 tools appear in the connectors list ✅

🛠️ The 6 available tools

🔒 Security

• OAuth 2.1 + PKCE S256 — secure authentication flow compliant with RFC 9728
• SHA-256 token hashing — tokens are never stored in plain text
• UFW — VM port 8000 open only from the NUC host (192.168.122.1)
• Systemd hardening — NoNewPrivileges, service isolated in the VM
• Targeted CF purge — only modified URLs are purged

🔄 Page modification flow

Claude.ai → create_page / update_page
                │
                ▼
        hugo-mcp writes the .md file
                │
                ▼
        deploy.sh: hugo --minify
                │
                ▼
        rsync public/ → /var/www/hugo/
                │
                ▼
        Cloudflare API: purge_cache (targeted)
                │
                ▼
        Page live in ~2 seconds

🏁 Conclusion

This stack transforms Hugo into an active context source for Claude.ai — create, modify, and manage the static site through conversation, with automatic rebuild and cache purge. The whole setup reuses the OAuth infrastructure already in place for Grav and is fully available on GitHub under the MIT license.

Next steps:

• 💡 Add a list_assets tool to manage images and static files
• 💡 Implement a Git webhook to automatically rebuild after a push
• 💡 Migrate content from Grav to Hugo by automating frontmatter conversion