Hugo MCP server

Hugo MCP server

A generic MCP (Model Context Protocol) server for any Hugo blog, deployed on Cloudflare Workers.

It reads your blog's llms.txt and llms-full.txt files and exposes them as structured tools that AI assistants (Claude, Cursor, and others) can query to understand your content.

How it works

Your Hugo blog           Cloudflare Worker          AI assistant
─────────────────        ──────────────────         ──────────────
/llms.txt          ───►  /mcp  (MCP tools)  ◄───►  Claude / Cursor
/llms-full.txt     ───►  /llms.txt (proxy)          etc.
                         /llms-full.txt (proxy)

The Worker fetches your blog's llms.txt and llms-full.txt at runtime (with an in-memory cache), and exposes three MCP tools:

Prerequisites

• A Hugo blog publicly accessible on the web
• llms.txt and llms-full.txt files in your Hugo static/ folder (see Step 1)
• A Cloudflare account (free tier is enough)
• Node.js ≥ 18
• Wrangler CLI (npm install -g wrangler)

Step 1 — Create your llms.txt files

llms.txt and llms-full.txt are plain-text files that describe your blog's content to language models. They live in your Hugo static/ folder and are served automatically at /llms.txt and /llms-full.txt.

Option A — Use the helper script

# Clone this repo
git clone https://github.com/your-username/hugo-llms-mcp.git
cd hugo-llms-mcp

# Edit the configuration at the top of the script
nano scripts/generate-llms.py

# Run it — outputs static/llms.txt and static/llms-full.txt
python3 scripts/generate-llms.py

Then copy the generated files to your Hugo site's static/ folder, review and enrich them manually, and redeploy your site.

Option B — Write them by hand

static/llms.txt (summary, ~50 lines):

# My Hugo Blog

> One-line tagline for your blog.

Author: Your Name
Site: https://your-hugo-blog.com
Language(s): English

## Description

Two or three sentences describing what the blog is about,
who the author is, and who it's for.

## Published content

- Post Title One (Month Year) — https://your-hugo-blog.com/posts/post-one/
- Post Title Two (Month Year) — https://your-hugo-blog.com/posts/post-two/

## Instructions for language models

- Content may be freely summarised with attribution and a link to the source.
- Short excerpts may be quoted for informational purposes.
- Reproduction of full articles is not permitted.

static/llms-full.txt (extended index, as long as needed):

# My Hugo Blog
# llms-full.txt — Extended index for language models

Site: https://your-hugo-blog.com
Author: Your Name
Generated: June 2026

---

## Author profile

A longer bio of the author.

---

## Content

---

### Post Title One

URL: https://your-hugo-blog.com/posts/post-one/
Date: January 2025
Description: A detailed summary of what this post covers,
key points made, people or places mentioned, and tone.

---

### Post Title Two

...

Tip: The more detailed llms-full.txt is, the more useful the search_content tool becomes. Include summaries, key locations, episode descriptions, and any cross-references between posts.

Verify the files are live

After deploying your Hugo site, check:

https://your-hugo-blog.com/llms.txt
https://your-hugo-blog.com/llms-full.txt

Both should return plain text. If they do, you're ready for Step 2.

Step 2 — Configure the Worker

Clone this repo (if you haven't already) and edit wrangler.toml:

name = "my-blog-mcp"            # becomes my-blog-mcp.<account>.workers.dev

[vars]
SITE_URL     = "https://your-hugo-blog.com"
SITE_NAME    = "My Hugo Blog"
CACHE_TTL_SEC = "3600"          # cache TTL in seconds; 0 = always fetch fresh

Step 3 — Deploy

# Install dependencies
npm install

# Log in to Cloudflare (once)
wrangler login

# Deploy
npm run deploy

Wrangler will print the Worker URL:

https://my-blog-mcp.<your-account>.workers.dev

Step 4 — Verify

# Health check
curl https://my-blog-mcp.<your-account>.workers.dev/health

# List MCP tools
curl -s -X POST https://my-blog-mcp.<your-account>.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | python3 -m json.tool

# Search for a keyword
curl -s -X POST https://my-blog-mcp.<your-account>.workers.dev/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_content","arguments":{"query":"your keyword","max_results":3}}}' | python3 -m json.tool

Step 5 — Connect to Claude

Claude.ai

Settings → Connectors → Add MCP Server:

https://my-blog-mcp.<your-account>.workers.dev/mcp

Claude Desktop

Install the mcp-remote bridge (needed because Claude Desktop doesn't yet support remote MCP natively):

npm install -g mcp-remote

Edit claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "my-blog": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://my-blog-mcp.<your-account>.workers.dev/mcp"
      ]
    }
  }
}

Restart Claude Desktop. The three tools will appear in the tool list.

Cursor / other MCP clients

Use the Worker URL directly: https://my-blog-mcp.<your-account>.workers.dev/mcp

Updating content

The Worker fetches content from your live site and caches it in memory for CACHE_TTL_SEC seconds (default: 1 hour). So when you publish new posts:

1. Update llms.txt and llms-full.txt in your Hugo static/ folder.
2. Redeploy your Hugo site — the Worker will pick up the changes automatically within the cache TTL.

No need to redeploy the Worker itself unless you change wrangler.toml or src/index.js.

Project structure

hugo-llms-mcp/
├── src/
│   └── index.js          ← Cloudflare Worker (MCP server logic)
├── scripts/
│   └── generate-llms.py  ← Helper to scaffold llms.txt files
├── wrangler.toml         ← Cloudflare configuration (edit this)
├── package.json
├── .gitignore
├── LICENSE
└── README.md

Cloudflare free tier limits

A typical blog MCP server uses well under all of these limits.

Real-world example

This project was originally built for ciclogravelista.com, a personal gravel cycling travel blog. The live MCP server is available at:

https://ciclogravelista-mcp.ciclogravelista.workers.dev/mcp

Source: github.com/your-username/ciclogravelista-mcp

License

MIT — see LICENSE.